Authentication and Authorization API Reference

The Plaid Authentication API provides a mechanism for integration partners to authenticate user attempts to connect accounts to Plaid apps. Successful authentication will return token-identifier pairs, which Plaid will subsequently use to refer to the user’s accounts. The API provides methods for the partner to refresh access tokens, as well as to revoke tokens unilaterally, and to communicate that revocation to Plaid.

Plaid will present two levels of authentication before requesting resources on behalf of the partner institution customers.

Plaid will present its credentials to the partner institution to confirm that its requests are authentic and originate from Plaid. These parameters are present, and must be verified, on every request:

Additionally, Plaid will only issue requests from pre-arranged IP addresses. The implementer must deny network traffic not originating from these addresses.

If a Plaid Exchange API implementation serves multiple institutions, it will be necessary for the integration to discriminate which institution a Plaid-originating request is targeting. The implementing partner is expected to make user identifiers globally unique across all institutions. A straightforward way to implement this is by prefixing user identifiers with the institution identifier.

Two API methods will communicate a pre-shared institution_id parameter, because they involve initial authentication, before unique user identifiers can be exchanged:

• Authentication API method
• Item Import API method

A unique institution_id should be assigned to each of the institutions that the integration serves, and those values should be shared with Plaid. Plaid will include the institution_id parameter on the above methods so that the integration can distinguish the institution that should be the target of a request.

Plaid will present user credentials in exchange for an access token, which will be presented on subsequent resource requests. The partner institution must validate that the provided access token corresponds to the requested user.

All requests which require per-user authentication will have the following parameters present in the request headers:

Plaid represents authorization at three levels of granularities: per-user, per-application, and per-account. Partner institutions can query and modify a user's authorization state at all granularities using the Authorization API.

An instance of per-user, per-application authorization is called an Item, which can optionally be scoped to individual accounts. For efficiency, Plaid schedules data accesses at the broadest granularity (per-user) and then provisions narrower granularities to Plaid clients. This access model ensures that each application can be given a single, consistent view of a user’s accounts.

Data access and retention

If a partner implementation produces data that Plaid is not authorized to receive or store, Plaid will discard those elements and they will not be stored. This alleviates the burden from an institution to filter its responses by consulting and applying granular access controls. However, the Authorization API enables institutions to develop such filtering capabilities.

The Authorization API provides partner institutions the ability to address authorized ClientApplications and, optionally, accounts on those applications. A ClientApplication contains enough information to create user experiences that provide the names of connected applications, link to the application developer, and describe which data elements are accessible to that application. Optionally, the access can be scoped to individual accounts. The authorization for an entire application, or individual accounts, can be revoked using the API.

Token revocation

If any request, to any endpoint, receives a response with a 401 Unauthorized HTTP status, Plaid will delete the token and mark the associated Item as lacking valid credentials. This will trigger a webhook notifying clients of the state transition, and advise them to prompt the end user to reauthenticate with Plaid. If a request is rejected with 403 Forbidden instead, then Plaid will advise the customer that the Item is locked and the user needs to return to the institution first. Use 405 Not Allowed to indicate that the institution has suspended third-party access to the account, for any reason.

The partner can use 401 Unauthorized to expire tokens when the user has changed their password or closed their account, and 403 Forbidden to indicate that access to the account is suspended. Both conditions will require a user to reauthenticate to the institution.

See the Authenticate User Credentials section for more information.

Token refresh

The partner may respond to any properly authenticated request in the Aggregation Flow with HTTP status code 205 Reset Content using an AuthorizationResponse response body to communicate the new token. Plaid will delete the old token and replace it with the token communicated in the response, then repeat the request.

Once the partner has issued the new token, all requests made with the previous token must receive a 401 Unauthorized response. Partner security policy concerning management of access tokens is outside the scope of this document, but the partner should consider retaining the list of recently deauthorized tokens, as attempts to reuse deauthorized tokens would be indicative of a breach.

The authentication flow has one essential method, Authentication User Credentials, to which credentials are presented. If authentication is successful, the API returns a token and a principal identifier for the user. These are used in all subsequent requests to address and access the user’s authenticated resources.

{
  "username": "jane@doe.com",
  "password": "keepyourpasswordsecret",
  "institution_id": "ins_1"
}

{
  "user_id": "YRQ8PPaohJ",
  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
}

202 Accepted

This response indicates that Plaid must challenge the user according to one of two escalated authentication strategies: knowledge-based authentication (KBA) or one-time passcode. Describing these strategies is beyond the scope of this document, and the partner institution is presumed to understand how to choose the appropriate strategy for its user base.

A 202 Accepted response does not indicate that the presented credentials are correct.

Request orchestration

The next request in the KBA and TOTP authentication flows will be to Validate MFA API method, and in the OTP it will be to Trigger OTP API method. (See the Authorization API Overview to understand the complete sequence.)

In exceptional situations, the flow may fail and be aborted. In that case, the end user may receive an error message and choose to restart the authentication attempt. The partner implementation must not expect the next request to be to this endpoint, because if the user has restarted the authentication flow, the next request would go to the Authentication API method and the implementation should expect a response to this endpoint.

MfaEscalationChallengeType

MfaEscalationChallenge

{
  "id": "string",
  "type": "otp"
}

MfaEscalationChallengeResponse

{
  "user_id": "v5z37MvUF7",
  "challenge": {
    "id": "jOSsqir1tc",
    "type": "kba",
    "questions": [
      {
        "id": "Z9D0iK",
        "text": "What city were you born in?"
      },
      {
        "id": "ch7SbY",
        "text": "Where did you go to high school?"
      },
      {
        "id": "36b4Xo",
        "text": "What is your mother's maiden name?"
      }
    ]
  }
}

MfaKbaQuestion

{
  "id": "string",
  "text": "string"
}

MfaTotpEscalationChallenge

{
  "type": "otp",
  "prompt": "Open the XYZ app to receive your code.",
  "id": "string"
}

MfaOtpEscalationChallenge

{
  "id": "string",
  "type": "otp",
  "send_methods": [
    {
      "id": "Z9D0iK",
      "mask": "(***) ***-8653",
      "type": "sms"
    },
    {
      "id": "36b4Xo",
      "mask": "j****@p****.com",
      "type": "email"
    }
  ]
}

MfaOtpSendMethod

{
  "id": "string",
  "mask": "(***) ***-8653",
  "type": "sms"
}

OtpSendMethodType

401 Unauthorized

The authentication credentials were rejected.

403 Forbidden

The user’s account is locked, typically due to excessive incorrect authentication attempts. This response will trigger messaging to the user indicating that the account has been temporarily locked, and will advise the user to contact the institution.

405 Not Allowed

This response should be used to indicate that the user’s account is not permitted to participate in aggregation, typically because the user must accept a license or terms of use. This will trigger messaging to the user indicating that the account is not yet authorized for online use, and will direct the user to visit the partner institution’s online portal for further guidance.

Plaid recommends that whatever pending terms or agreements that block this use case be presented to the user immediately upon login.

{
  "challenge_id": "jOSsqir1tc",
  "send_method_id": "Z9D0iK"
}

200 OK

This response indicates that the send method was acceptable and the partner institution will transmit the passcode to the user. No response body is required.

400 Bad Request

This response indicates that the send method was not acceptable.

Receive and authenticate the user’s response to the escalation challenge. This endpoint receives both KBA responses and (T)OTP passcodes in the form of ValidateChallengeRequest instances.

{
  "challenge_id": "jOSsqir1tc"
}

{
  "passcode": "123456",
  "challenge_id": "jOSsqir1tc"
}

{
  "answers": [
    {
      "question_id": "Z9D0iK",
      "text": "San Francisco"
    }
  ],
  "challenge_id": "jOSsqir1tc"
}

{
  "question_id": "Z9D0iK",
  "text": "San Francisco"
}

Plaid Exchange supports user authentication via redirection, utilizing a token exchange protocol compatible with OAuth.

1. The institution registers with Plaid an authentication URL. Plaid will redirect users to this URL to authenticate after they select an institution in Link.
2. Plaid will generate a URL with the following query parameters. institution_id is included to facilitate platforms that support more than one institution. application_id is to identify the Plaid client who is creating a connection.
   • state=<PLAID_GENERATED>
   • response_type=code
   • redirect_uri=<PLAID_GENERATED>
   • client_id=PLAID
   • institution_id=ins_<YOUR_INSTITUTION_ID>
   • application_id=<PLAID_APPLICATION_ID>
   • plaid_trusted_auth_token=<PLAID_GENERATED> (only present for Trusted Auth integrations)
3. The user is subsequently redirected, and completes authentication on the institution's domain. Prior to proceeding with authentication, the institution MUST verify that the redirect_uri query parameter has previously been registered to Plaid. See RFC 6749 Section 3.1.2.2.
   • On success, the institution redirects back to Plaid (via the redirect_uri) with the state and code query parameters. The code query parameter contains the authorization code granted by the institution.
   • On failure, the institution redirects back to Plaid (via the redirect_uri) with a state, error, and optional error_description query parameters.
   • In addition to the standard OAuth error codes, Plaid recommends the following error codes to deliver more granular errors to the consumer:
     • user_denied_access - used when the user has explicitly denied access.
     • user_exited - used when the user has clicked a button to exit the flow without accepting or denying.
   • See RFC 6749 Section 4.1.2
4. Subsequently, Plaid will exchange the supplied authorization code for a persistent access token using this endpoint. On success, this endpoint must return an auth_token as described in Token Management.
   • Plaid will authenticate itself via the X-PLAID-CLIENT-ID and X-PLAID-SECRET headers, as described in Plaid Authentication
   • This endpoint MUST verify Plaid's credentials.
   • The endpoint MAY verify that the request comes from one of Plaid's IP addresses, previously communicated to the financial institution.
   • The endpoint MUST ensure that the supplied authorization code was issued to Plaid.
   • The endpoint MUST ensure that the authorization code is valid.
   • The institution MAY implement a TTL on the authorization code, consistent with OAuth best practices.
   • The institution MUST verify that the redirect_uri is the same one sent in the initial authentication request.

{
  "state": "vEPcsYYKyf9iDfZnJZWjtZSJUiLr3JxE",
  "response_type": "code",
  "redirect_uri": "https://cdn.plaid.com/link/v2/stable/oauth.html",
  "client_id": "PLAID",
  "institution_id": "ins_1",
  "application_id": "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
}

{
  "user_id": "YRQ8PPaohJ",
  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
}

401 Unauthorized

The response was not accepted. Plaid will assume that the flow should be aborted and will prompt the user to retry.

{
  "client_id": "m08CZWsDA8vMDSg2n1IHRJcfzOe",
  "secret": "0wdBo8AzXz82e7tBZfRlDA8XJwE",
  "access_token": "access-production-248e9592-ca5f-463a-b4b5-e8d10b6e9e98"
}

{
  "applications": [
    {
      "requested_scopes": {
        "optional_product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        },
        "account_filters": {
          "loan": [
            "loan",
            "loan"
          ],
          "investment": [
            "investment",
            "investment"
          ],
          "depository": [
            "depository",
            "depository"
          ],
          "credit": [
            "credit",
            "credit"
          ]
        },
        "required_product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        }
      },
      "reason_for_access": "Help users track their account balances",
      "name": "FtchApp",
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "product_data_types": [
        "ACCOUNT_BALANCE",
        "ACCOUNT_USER_INFO"
      ],
      "logo": "https://example.com/FtchAppLogo.png",
      "scopes": {
        "product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        },
        "new_accounts": true,
        "accounts": [
          {
            "unique_id": "unique_id",
            "authorized": true
          },
          {
            "unique_id": "unique_id",
            "authorized": true
          }
        ]
      },
      "application_id": "qPMq5j5FpvUCGk9YZ9qmNX3GZDt",
      "application_url": "https://example.com"
    },
    {
      "requested_scopes": {
        "optional_product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        },
        "account_filters": {
          "loan": [
            "loan",
            "loan"
          ],
          "investment": [
            "investment",
            "investment"
          ],
          "depository": [
            "depository",
            "depository"
          ],
          "credit": [
            "credit",
            "credit"
          ]
        },
        "required_product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        }
      },
      "reason_for_access": "Help users to track their account balances",
      "name": "FtchApp",
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "product_data_types": [
        "ACCOUNT_BALANCE",
        "ACCOUNT_USER_INFO"
      ],
      "logo": "https://example.com/FtchAppLogo.png",
      "scopes": {
        "product_access": {
          "auth": true,
          "identity": true,
          "statements": true,
          "transactions": true
        },
        "new_accounts": true,
        "accounts": [
          {
            "unique_id": "unique_id",
            "authorized": true
          },
          {
            "unique_id": "unique_id",
            "authorized": true
          }
        ]
      },
      "application_id": "qPMq5j5FpvUCGk9YZ9qmNX3GZDt",
      "application_url": "https://example.com"
    }
  ]
}

400 Bad Request

Data is malformed; the corresponding Item could not be found; or the secret, client_id, or access_token could not be validated.

404 Not Found

No applications could be found for the corresponding Item.

{
  "client_id": "m08CZWsDA8vMDSg2n1IHRJcfzOe",
  "secret": "0wdBo8AzXz82e7tBZfRlDA8XJwE",
  "user_auth": {
    "user_id": "6gXfjEcgqcjTVnUgbTwDF3DTeiQ",
    "auth_token": "E213KdjipES98P95BUCtodphG9D"
  },
  "account_ids": [
    "string"
  ],
  "products": [
    "transactions"
  ]
}

{
  "access_token": "access-production-c2541188-d26f-4953-985a-b11adcc878b7"
}

{
  "client_id": "m08CZWsDA8vMDSg2n1IHRJcfzOe",
  "secret": "0wdBo8AzXz82e7tBZfRlDA8XJwE",
  "user": {
    "client_user_id": "myuser-1234"
  },
  "access_token": "access-production-248e9592-ca5f-463a-b4b5-e8d10b6e9e98",
  "products": [
    "auth"
  ],
  "cross_app_item_add": {
    "target_application_token": "application-production-ad1b1305-f43d-41b7-a99f-84003b11b3ab",
    "foreign_id": "myapp-335e8b1ba75843cab42a81f9f7819396"
  }
}

{
  "expiration": "2000-01-23T04:56:07.000+00:00",
  "token": "link-production-b479d0d5-7618-4969-b9ab-458165f8a4f2"
}

Plaid sends a webhook to the target partner once an Item has been created via the cross-application Item creation flow in Link

{
  "client_id": "m08CZWsDA8vMDSg2n1IHRJcfzOe",
  "secret": "0wdBo8AzXz82e7tBZfRlDA8XJwE",
  "access_token": "access-production-248e9592-ca5f-463a-b4b5-e8d10b6e9e98",
  "application_id": "TZ9Bh7PQX6S3ZRRPtq7lv5QFkap"
}

200 OK

The request is valid and the application was unlinked.

400 Bad Request

Data is malformed or the secret, client_id, or access_token could not be validated. Application is not unlinked.

404 Not Found

Provided application could not be found via its application_id; application is not unlinked.

{
  "request_id": "Asfa1gfAdcxIz"
}

{
  "client_id": "m08CZWsDA8vMDSg2n1IHRJcfzOe",
  "secret": "0wdBo8AzXz82e7tBZfRlDA8XJwE",
  "application_id": "qPMq5j5FpvUCGk9YZ9qmNX3GZDt"
}

{
  "reason_for_access": "Help users track their account balances",
  "name": "FtchApp",
  "created_at": "2000-01-23T04:56:07.000+00:00",
  "logo": "https://example.com/FtchAppLogo.png",
  "application_id": "qPMq5j5FpvUCGk9YZ9qmNX3GZDt",
  "application_url": "https://example.com"
}