OAuth overview
Use OAuth to connect a customer's Link account to your hosted application. The same authorization flow supports payments and financial insights. Request only the access your feature needs.
The Link API lives at api.link.com and authorizes against login.link.com, separate from api.stripe.com. You authenticate API requests with an OAuth access token that represents one customer. Stripe secret keys and restricted API keys don't work, and the Stripe server-side SDKs don't cover these endpoints.
Choose an authorization flow
A hosted application uses the OAuth 2.0 authorization-code flow with a confidential client. Your server owns the client secret, authorization state, token exchange, storage, refresh, and revocation.
For an agent running locally, use the Link CLI quickstart or the financial insights CLI setup. Customers using the local CLI flow don't need to register a confidential OAuth client.
Hosted authorization requirements
Prepare the following before connecting a customer's Link account:
- A registered OAuth client, including a
client_id,client_secret, and exact redirect URIs. Follow OAuth client registration if you don't have these yet. - The Stripe publishable key from the API keys in your Dashboard.
- A server-side callback at a registered redirect URI, a session store for authorization state, and secure storage for access and refresh tokens.
Check the feature-specific requirements before requesting access: payment eligibility or financial insights prerequisites and Financial Connections registration.
Register a hosted OAuth client
Skip this step if you already have a registered client. Create a Stripe account, then apply for an OAuth client through the registration form. Provide your app name, a description, and the exact redirect URIs you need. Matching is exact, so register every URI. Stripe sends you a client_id and client_secret.
Redirect the customer to Link
Generate a Proof Key for Code Exchange (PKCE) verifier and challenge. Store the verifier and a random state value in the customer's server-side session, then redirect them to the authorization URL. This example requests payment access and customer information:
https://login.link.com/auth?key=pk_live_YOUR_PUBLISHABLE_KEY&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code&scope=payment_methods.agentic%20userinfo:read&state=RANDOM_STATE_VALUE&code_challenge=YOUR_PKCE_CODE_CHALLENGE&code_challenge_method=S256URL-encode every parameter value. The parameters are:
| Parameter | Value |
|---|---|
key | Your Stripe publishable key. |
client_id | The OAuth client ID from Stripe. |
redirect_uri | An exact match for a URI registered with your OAuth client. |
response_type | code |
scope | Space-separated (%20) or comma-separated scopes. See Scopes. |
state | A random value that you verify on callback to prevent cross-site request forgery (CSRF). |
code_challenge | Optional for confidential clients, but recommended. BASE64URL(SHA256(code_verifier)), using a random, URL-safe verifier 43–128 characters long. |
code_challenge_method | S256. Required if you send code_challenge. Link rejects any other value. |
authorization_details | A URL-encoded JSON array of the financial data source actions you need. See Request financial data scopes. |
Scopes
Request the scopes your feature needs:
| Scope | Use it to |
|---|---|
payment_methods.agentic | Create spend requests and retrieve credentials. Required for every payment integration. |
userinfo:read | Read the customer's name and email to prefill forms and check eligibility. |
financial_insights.sources.read, financial_insights.balances.read, financial_insights.transactions.read | Read financial data. These pair with the authorization_details parameter described in Financial insights. |
Before redirecting the customer for financial insights, follow the hosted setup for registration requirements and source actions. Its authorization example covers insights alone or alongside payments.
Handle the OAuth callback
After the customer authenticates and approves access, Link redirects to your callback with code and state. Verify state before doing anything else. The authorization code is single-use. Exchange it within 5 minutes. If authorization fails, Link redirects with an error instead of a code.
This callback is the registered OAuth redirect_uri. A spend request's completion callback is separate and doesn't complete OAuth authorization.
Exchange the code for tokens
Exchange the code from your server. Send your publishable key in the Authorization header, and include the original PKCE verifier:
curl -X POST https://login.link.com/auth/token \
-H "Authorization: Bearer pk_live_YOUR_PUBLISHABLE_KEY" \
-d "grant_type=authorization_code" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=https://yourapp.com/callback" \
-d "code=AUTHORIZATION_CODE" \
-d "code_verifier=YOUR_PKCE_CODE_VERIFIER"Link returns both tokens:
{
"access_token": "liwltoken_...",
"refresh_token": "liwlrefresh_...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "payment_methods.agentic userinfo:read"
}The response echoes the scope (and authorization_details) the customer actually granted. A customer can approve only a subset, so read it instead of assuming you received everything you asked for.
Store and manage tokens
Store both tokens securely on your server. Access tokens last one hour. Refresh tokens last one year and rotate every time they're used. Atomically replace the stored refresh token with the new one from each refresh response.
Your credential manager should track token expiry, coalesce concurrent refreshes, persist rotated refresh tokens safely, and keep all tokens out of agent context, logs, and client-side code.
The SDKs accept an OAuth access token, but they don't perform sign-in, persist credentials, or own refresh tokens. Supply the current access token using the client setup for TypeScript, Go, or Python.
Refresh and revoke access
Refresh before the access token expires instead of waiting for a 401:
curl -X POST https://login.link.com/auth/token \
-H "Authorization: Bearer pk_live_YOUR_PUBLISHABLE_KEY" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "refresh_token=CURRENT_REFRESH_TOKEN"When a customer disconnects your application, revoke their refresh token. Revoking it ends the grant and invalidates the access tokens issued from it:
curl -X POST https://login.link.com/auth/revoke \
-H "Authorization: Bearer pk_live_YOUR_PUBLISHABLE_KEY" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "token=TOKEN_TO_REVOKE" \
-d "token_type_hint=refresh_token"Next steps
Continue with the payments guide or financial insights guide for your feature's workflow.