OAuth
API reference for Plaid OAuth endpoints
| Endpoints | |
|---|---|
/oauth/token | Create or refresh an OAuth access token |
/oauth/introspect | Get metadata about an OAuth token |
/oauth/revoke | Revoke an OAuth token |
These endpoints are for customers, partners and services that are integrating with Plaid's OAuth service to obtain a token for sharing consumer reports or accessing the Plaid Dashboard or other Plaid services. 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.
Request fields
grant_typeclient_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.refresh_token, urn:ietf:params:oauth:grant-type:token-exchange, client_credentialsclient_idclient_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_secretsecret. 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.secretsecret. 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.scopeuser: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_tokenresourceaudiencesubject_token_type:- For
urn:plaid:params:tokens:user: Must be the same as theclient_id. - For
urn:plaid:params:oauth:user-token: The otherclient_idto exchange tokens to. - For
urn:plaid:params:credit:multi-user: aclient_idor one of the supported CRA partner URNs:urn:plaid:params:cra-partner:experian,urn:plaid:params:cra-partner:fannie-mae, orurn:plaid:params:cra-partner:freddie-mac.
subject_tokensubject token must be an OAuth refresh token issued from the /oauth/token endpoint. The meaning depends on the subject_token_type.subject_token_typeurn: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.urn:plaid:params:tokens:user, urn:plaid:params:oauth:user-token, urn:plaid:params:credit:multi-userconst request = {
grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
scope: 'user:read',
subject_token_type: 'urn:plaid:params:credit:multi-user',
audience: 'urn:plaid:params:cra-partner:fannie-mae',
subject_token: userToken
};
try {
const response = await client.oauthToken(request);
} catch (error) {
...
}
Response fields
access_tokenrefresh_tokentoken_typeexpires_inrequest_id{
"access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==",
"refresh_token": "pdr--viXurkDg88d5zf8m6Wl0g==",
"expires_in": 900,
"token_type": "Bearer",
"request_id": "m8MDqcS6F3lzqvP"
}/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.
Request fields
tokenrefresh_token, access_token, etc)client_idclient_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_secretsecret. 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.secretsecret. 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.const request = {
token: accessToken
};
try {
const response = await client.oauthIntrospect(request);
} catch (error) {
...
}
Response fields
activetrue value indicates that the token has been issued, has not been revoked, and is within the time window of validity.scopeuser: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_idclient_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.expiatsubaudisstoken_typeuser_idrequest_id{
"active": true,
"scope": "user:read user:write exchange",
"client_id": "68028ce48d2b0dec68747f6c",
"exp": 1670000000,
"iat": 1670000000,
"sub": "68028ce48d2b0dec68747f6c",
"aud": "https://production.plaid.com",
"iss": "https://production.plaid.com",
"token_type": "Bearer",
"request_id": "m8MDqcS6F3lzqvP"
}/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.
Request fields
tokenrefresh_token, access_token, etc)client_idclient_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_secretsecret. 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.secretsecret. 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.const request = {
token: accessToken
};
try {
const response = await client.oauthRevoke(request);
} catch (error) {
...
}
Response fields
request_id{
"request_id": "m8MDqcS6F3lzqvP"
}