plaid

Create or refresh an OAuth access token

Changed on

/oauth/token issues an access token and refresh token depending on the grant_type provided. This endpoint supports Content-Type: application/x-www-form-urlencoded as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification.

post/oauth/token

Request

  • Base URL
    https://production.plaid.com
  • URL
    https://production.plaid.com/oauth/token
  • Auth
    API key in header PLAID-CLIENT-ID and API key in header PLAID-SECRET and API key in header Plaid-Version

Request body

grant_type'refresh_token' | 'urn:ietf:params:oauth:grant-type:token-exchange' | 'client_credentials' required

The type of OAuth grant being requested:

client_credentials allows exchanging a client id and client secret for a refresh and access token.

refresh_token allows refreshing an access token using a refresh token. When using this grant type, only the refresh_token field is required (along with the client_id and client_secret).

urn:ietf:params:oauth:grant-type:token-exchange allows exchanging a subject token for an OAuth token. When using this grant type, the audience, subject_token and subject_token_type fields are required.

These grants are defined in their respective RFCs. refresh_token and client_credentials are defined in RFC 6749 and urn:ietf:params:oauth:grant-type:token-exchange is defined in RFC 8693.

client_idstring

Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.

client_secretstring

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body as either secret or client_secret.

secretstring

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body as either secret or client_secret.

scopestring

A space-separated list of scopes associated with this token, in the format described in https://datatracker.ietf.org/doc/html/rfc6749#section-3.3. Currently accepted values are:

user:read allows reading user data.

user:write allows writing user data.

exchange allows exchanging a token using the urn:plaid:params:oauth:user-token subject token type.

mcp:dashboard allows access to the MCP dashboard server.

refresh_tokenstring

Refresh token for OAuth

resourcestring

URI of the target resource server

audiencestring

Used when exchanging a token. The meaning depends on the subject_token_type:

  • For urn:plaid:params:tokens:user: Must be the same as the client_id.
  • For urn:plaid:params:oauth:user-token: The other client_id to exchange tokens to.
  • For urn:plaid:params:credit:multi-user: a client_id or one of the supported CRA partner URNs: urn:plaid:params:cra-partner:experian, urn:plaid:params:cra-partner:fannie-mae, or urn:plaid:params:cra-partner:freddie-mac.
subject_tokenstring

Token representing the subject. The meaning depends on the subject_token_type. For urn:plaid:params:tokens:user, the subject_token must be a Plaid-issued user token from the /user/create endpoint. For urn:plaid:params:oauth:user-token, the subject_token must be an OAuth refresh token issued from the /oauth/token endpoint.

subject_token_type'urn:plaid:params:tokens:user' | 'urn:plaid:params:oauth:user-token' | 'urn:plaid:params:credit:multi-user'

The type of the subject token.

urn:plaid:params:tokens:user allows exchanging a Plaid-issued user token for an OAuth token. When using this token type, audience must be the same as the client_id. subject_token must be a Plaid-issued user token issued from the /user/create endpoint.

urn:plaid:params:oauth:user-token allows exchanging a refresh token for an OAuth token to another client_id. The other client_id is provided in audience. subject_token must be an OAuth refresh token issued from the /oauth/token endpoint.

urn:plaid:params:credit:multi-user allows exchanging a Plaid-issued user token for an OAuth token. When using this token type, audience may be a client id or a supported CRA partner URN. audience supports a comma-delimited list of clients. When multiple clients are specified in the audience a multi-party token is created which can be used by all parties in the audience in conjunction with their client_id and client_secret.

Example request

{
  "scope": "user:read user:write exchange",
  "resource": "https://production.plaid.com",
  "audience": "68028ce48d2b0dec68747f6c",
  "subject_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"
}

Response

OK

access_tokenstring required

Access token for OAuth

refresh_tokenstring required

Refresh token for OAuth

token_typestring required

The type of the returned token. Bearer for OAuth access tokens.

expires_ininteger required

Time remaining in seconds before expiration.

request_idstring required

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Example response

{
  "token_type": "Bearer",
  "expires_in": 900
}

Changes

  • 83dc2757b74eRevision changes
    • info

      added the new urn:plaid:params:credit:multi-user enum value to the request property

  • bb819dcb75b3Revision changes
    • breaking

      removed the enum value urn:plaid:params:tokensdb:user-token of the request property

    • info

      added the new urn:plaid:params:tokens:user enum value to the request property