Skip to content
Logo

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.

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=S256

URL-encode every parameter value. The parameters are:

ParameterValue
keyYour Stripe publishable key.
client_idThe OAuth client ID from Stripe.
redirect_uriAn exact match for a URI registered with your OAuth client.
response_typecode
scopeSpace-separated (%20) or comma-separated scopes. See Scopes.
stateA random value that you verify on callback to prevent cross-site request forgery (CSRF).
code_challengeOptional for confidential clients, but recommended. BASE64URL(SHA256(code_verifier)), using a random, URL-safe verifier 43–128 characters long.
code_challenge_methodS256. Required if you send code_challenge. Link rejects any other value.
authorization_detailsA URL-encoded JSON array of the financial data source actions you need. See Request financial data scopes.

Scopes

Request the scopes your feature needs:

ScopeUse it to
payment_methods.agenticCreate spend requests and retrieve credentials. Required for every payment integration.
userinfo:readRead the customer's name and email to prefill forms and check eligibility.
financial_insights.sources.read, financial_insights.balances.read, financial_insights.transactions.readRead 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.