Sign in
plaid

Create or refresh an OAuth access token

/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 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 JSON string containing 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 grant 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.

subject_tokenstring

Token representing the subject. The subject token must be an OAuth refresh token issued from the /oauth/token endpoint. The meaning depends on the subject_token_type.

subject_token_type'urn:plaid:params:tokensdb::user-token' | 'urn:plaid:params:oauth::user-token'

The type of the subject token.

  • urn:plaid:params:tokensdb::user-token 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.

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

type of token the access token is. Currently it is always Bearer

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": 500
}

Changes