Sample - Plaid API
POST/oauth/token

Create or refresh an OAuth access token

Creates or refreshes OAuth access and refresh tokens according to the requested grant. Set grant_type to refresh_token, urn:ietf:params:oauth:grant-type:token-exchange, or client_credentials, and send the request as JSON or form-encoded data.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

10 body fields

OAuth token grant request, accepted as JSON or application/x-www-form-urlencoded data.

grant_typestringrequired
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.
Allowed:refresh_tokenurn:ietf:params:oauth:grant-type:token-exchangeclient_credentials
client_idstringoptional
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_secretstringoptional
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`.
secretstringoptional
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`.
scopestringoptional
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](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_tokenstringoptional
Refresh token for OAuth
resourcestringoptional
URI of the target resource server
audiencestringoptional
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_tokenstringoptional
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_typestringoptional
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`.
Allowed:urn:plaid:params:tokens:userurn:plaid:params:oauth:user-tokenurn:plaid:params:credit:multi-user

2 status codes
200Returns the OAuth `access_token`, `refresh_token`, `token_type`, remaining lifetime in `expires_in` seconds, and a `request_id`.
access_tokenstringrequired
Access token for OAuth
refresh_tokenstringrequired
Refresh token for OAuth
token_typestringrequired
The type of the returned token. `Bearer` for OAuth access tokens.
expires_inintegerrequired
Time remaining in seconds before expiration.
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
defaultError response.
errorstringoptional
OAuth error code
Allowed:invalid_requestinvalid_clientinvalid_grantunauthorized_clientinvalid_scopeunsupported_grant_type
error_descriptionstringoptional
A human-readable description of the error
error_uristringoptional
A URI identifying the specific error
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Error handling

grant_type is required and must be refresh_token, urn:ietf:params:oauth:grant-type:token-exchange, or client_credentials. Supply the fields associated with the selected grant, including refresh_token for refresh grants and a valid subject token and subject_token_type for token exchange.