OAuth

API reference for Plaid OAuth endpoints

Endpoints
/oauth/tokenCreate or refresh an OAuth access token
/oauth/introspectGet metadata about an OAuth token
/oauth/revokeRevoke an OAuth token

These endpoints are for partners and services that are integrating with Plaid's OAuth service to obtain a token for accessing the Plaid Dashboard or other Plaid services as a third party. They are not used for the Plaid Link flow where end users connect their financial institution accounts to Plaid using a bank's OAuth service. If you are a Plaid customer trying to ensure your app supports OAuth-based bank connections, see the OAuth Guide instead.

Endpoints

=*=*=*=

/oauth/token

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.

oauth/token

Request fields

grant_type
requiredstringrequired, string
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.

Possible values: refresh_token, urn:ietf:params:oauth:grant-type:token-exchange, client_credentials
client_id
stringstring
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_secret
stringstring
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.
secret
stringstring
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.
scope
stringstring
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_token
stringstring
Refresh token for OAuth
resource
stringstring
URI of the target resource server
audience
stringstring
Used when exchanging a token. The meaning depends on the subject_token_type.
subject_token
stringstring
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
stringstring
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.


Possible values: urn:plaid:params:tokensdb:user-token, urn:plaid:params:oauth:user-token
1Sample code coming soon!
oauth/token

Response fields and example

access_token
stringstring
Access token for OAuth
refresh_token
stringstring
Refresh token for OAuth
token_type
stringstring
type of token the access token is. Currently it is always Bearer
expires_in
integerinteger
time remaining in seconds before expiration
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==",
3  "refresh_token": "pdr--viXurkDg88d5zf8m6Wl0g==",
4  "expires_in": 900,
5  "token_type": "Bearer",
6  "request_id": "m8MDqcS6F3lzqvP"
7}
=*=*=*=

/oauth/introspect

Get metadata about an OAuth token

/oauth/introspect returns metadata about an access token or refresh token.
Note: 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.

oauth/introspect

Request fields

token
requiredstringrequired, string
An OAuth token of any type (refresh_token, access_token, etc)
client_id
stringstring
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_secret
stringstring
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.
secret
stringstring
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.
1Sample code coming soon!
oauth/introspect

Response fields and example

active
booleanboolean
Boolean indicator of whether or not the presented token is currently active. A true value indicates that the token has been issued, has not been revoked, and is within the time window of validity.
scope
stringstring
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.
client_id
stringstring
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.
exp
integerinteger
Expiration time as UNIX timestamp since January 1 1970 UTC
iat
integerinteger
Issued at time as UNIX timestamp since January 1 1970 UTC
sub
stringstring
Subject of the token
aud
stringstring
Audience of the token
iss
stringstring
Issuer of the token
token_type
stringstring
Type of the token
user_id
stringstring
User ID of the token
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "active": true,
3  "scope": "user:read user:write exchange",
4  "client_id": "68028ce48d2b0dec68747f6c",
5  "exp": 1670000000,
6  "iat": 1670000000,
7  "sub": "68028ce48d2b0dec68747f6c",
8  "aud": "https://production.plaid.com",
9  "iss": "https://production.plaid.com",
10  "token_type": "Bearer",
11  "request_id": "m8MDqcS6F3lzqvP"
12}
=*=*=*=

/oauth/revoke

Revoke an OAuth token

/oauth/revoke revokes an access or refresh token, preventing any further use. If a refresh token is revoked, all access and refresh tokens derived from it are also revoked, including exchanged tokens.
Note: 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.

oauth/revoke

Request fields

token
requiredstringrequired, string
An OAuth token of any type (refresh_token, access_token, etc)
client_id
stringstring
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_secret
stringstring
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.
secret
stringstring
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.
1Sample code coming soon!
oauth/revoke

Response fields and example

request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "m8MDqcS6F3lzqvP"
3}