Consent API

The Consent API represents each of your customers' authorizations as an FDX consent grant: a record of which application has access, which of the customer's resources it can read, which data clusters are in scope, and how long that access lasts.

Use it to build a consumer-facing consent portal, to answer support requests about a customer's connections, and to revoke access when a customer withdraws consent. Single-institution accounts can read the same data with no code in the Data Partner Dashboard; this page covers the API, which is available to every integration model, including platforms.

For conceptual background on authorization records, revocation, and the webhooks that accompany these endpoints, see Consent management.

Find your client_id and secret on the Developer > Keys tab of the Data Partner Dashboard and include both as the PLAID-CLIENT-ID and PLAID-SECRET headers, or as client_id and secret in the request body. All requests must be made over HTTPS.

Every consent grant is scoped to a customerId, which must be the same persistent, unique identifier you use as the sub claim in your OIDC ID token. See Unique user identifier (consistency key).

If you are a platform or gateway serving multiple institutions, Plaid assumes customerId is unique across all of them. If you reuse a customer identifier across institutions, contact your Plaid solutions engineering team before you integrate.

A consent grant covers a set of resources, each with a list of FDX data clusters. resources is omitted entirely when a grant covers none. resourceType is one of ACCOUNT, CUSTOMER, or DOCUMENT, and the clusters Plaid may request are:

Plaid uses a different, consumer-facing taxonomy for these clusters in the Link flow. Contact your Plaid solutions engineering team if you need the mapping between the two.

Fetch this list each time a customer opens your consent portal rather than serving a cached copy, so that revocations made elsewhere in the ecosystem are reflected immediately. Omit status to return grants in every state, which is useful for an audit view.

curl -X GET 'https://production.plaid.com/fdx/consents?customerId=<customer_id>&status=ACTIVE' \
  -H 'PLAID-CLIENT-ID: <client_id>' \
  -H 'PLAID-SECRET: <secret>'

{
  "consent_grants": [
    {
      "id": "9585694d-3ae5-8863-1234-567890abcdef",
      "status": "ACTIVE",
      "createdTime": "2026-01-01T00:00:00Z",
      "updatedTime": "2026-01-01T00:00:00Z",
      "parties": [
        {
          "name": "My Example Client",
          "type": "DATA_RECIPIENT",
          "homeUri": "https://example.com",
          "registry": "PRIVATE",
          "registeredEntityName": "My Example Client LLC",
          "registeredEntityId": "549300A0B1C2D3E4F5G6"
        },
        {
          "name": "First Platypus Bank",
          "type": "DATA_PROVIDER",
          "homeUri": "https://www.platypus.com"
        },
        {
          "name": "Plaid",
          "type": "DATA_ACCESS_PLATFORM",
          "homeUri": "https://plaid.com"
        }
      ],
      "resources": [
        {
          "resourceType": "ACCOUNT",
          "resourceId": "b14e1e714693bc00",
          "dataClusters": [
            "ACCOUNT_BASIC",
            "ACCOUNT_DETAILED",
            "STATEMENTS"
          ]
        }
      ]
    },
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
      "status": "REVOKED",
      "createdTime": "2026-01-03T00:00:00Z",
      "updatedTime": "2026-01-04T00:00:00Z",
      "parties": [
        {
          "name": "Another Example Client",
          "type": "DATA_RECIPIENT",
          "homeUri": "https://another-example.com",
          "registry": "PRIVATE",
          "registeredEntityName": "Another Example Client LLC",
          "registeredEntityId": "549300Z9Y8X7W6V5U4T3"
        },
        {
          "name": "First Platypus Bank",
          "type": "DATA_PROVIDER",
          "homeUri": "https://www.platypus.com"
        },
        {
          "name": "Plaid",
          "type": "DATA_ACCESS_PLATFORM",
          "homeUri": "https://plaid.com"
        }
      ],
      "resources": [
        {
          "resourceType": "ACCOUNT",
          "resourceId": "c25f2f825704cd11",
          "dataClusters": [
            "ACCOUNT_BASIC",
            "ACCOUNT_DETAILED"
          ]
        }
      ]
    }
  ]
}

Use the parties array to identify the application: the entry with type of DATA_RECIPIENT is the connected app, DATA_PROVIDER is you, and DATA_ACCESS_PLATFORM is Plaid.

If you have an existing live integration and need the consentId values for connections that predate it, contact your Plaid solutions engineering team to coordinate a backfill.

curl -X GET 'https://production.plaid.com/fdx/consents/<consent_id>' \
  -H 'PLAID-CLIENT-ID: <client_id>' \
  -H 'PLAID-SECRET: <secret>'

{
  "id": "9585694d-3ae5-8863-1234-567890abcdef",
  "status": "ACTIVE",
  "createdTime": "2026-01-01T00:00:00Z",
  "updatedTime": "2026-01-01T00:00:00Z",
  "parties": [
    {
      "name": "My Example Client",
      "type": "DATA_RECIPIENT",
      "homeUri": "https://example.com",
      "registry": "PRIVATE",
      "registeredEntityName": "My Example Client LLC",
      "registeredEntityId": "549300A0B1C2D3E4F5G6"
    },
    {
      "name": "First Platypus Bank",
      "type": "DATA_PROVIDER",
      "homeUri": "https://www.platypus.com"
    },
    {
      "name": "Plaid",
      "type": "DATA_ACCESS_PLATFORM",
      "homeUri": "https://plaid.com"
    }
  ],
  "resources": [
    {
      "resourceType": "ACCOUNT",
      "resourceId": "b14e1e714693bc00",
      "dataClusters": [
        "ACCOUNT_BASIC",
        "BALANCES",
        "TRANSACTIONS",
        "SCHEDULED_PAYMENTS"
      ]
    }
  ]
}

Call this endpoint as soon as a customer disconnects an application in your portal, or when your own risk or compliance systems terminate access. Plaid then notifies the application and stops serving it data, which is what keeps your portal, Plaid, and the application in sync. See Revocation and ecosystem sync for what happens if you skip this call.

Set initiator to the party that triggered the revocation, usually DATA_PROVIDER. Set reason to USER_ACTION when a customer disconnects the app themselves, or BUSINESS_RULE or SECURITY_EVENT when you revoke on your own initiative. If you pass OTHER, describe the circumstances in otherReason.

A successful revocation returns 204 No Content with an empty body. Revocation is not idempotent: a grant that is already revoked or expired returns 409 CONFLICT rather than succeeding again. Revocation is also per grant, so a customer with several grants for the same application needs a call for each consentId.

curl -X PUT 'https://production.plaid.com/fdx/consents/<consent_id>/revocation' \
  -H 'PLAID-CLIENT-ID: <client_id>' \
  -H 'PLAID-SECRET: <secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiator": "DATA_PROVIDER",
    "reason": "USER_ACTION"
  }'

Use this endpoint to show a customer when and why access ended, and to keep an audit record of who initiated it. Records are returned most recent first, and the array is empty for a grant that has never been revoked.

curl -X GET 'https://production.plaid.com/fdx/consents/<consent_id>/revocation' \
  -H 'PLAID-CLIENT-ID: <client_id>' \
  -H 'PLAID-SECRET: <secret>'

{
  "revocations": [
    {
      "status": "REVOKED",
      "reason": "USER_ACTION",
      "initiator": "DATA_PROVIDER",
      "updatedTime": "2026-01-03T00:00:00Z"
    }
  ]
}

A consent grant is normally created when a customer authorizes an application through your OAuth flow. To exercise these endpoints in Sandbox without a live connection, seed a grant with /sandbox/fdx/consent/seed and then list, retrieve, and revoke it as you would in production.

Pass consent_id to control the identifier of the seeded grant, which makes tests deterministic; omit it and Plaid generates one. Seeding fails if a grant with that identifier already exists.

Revoking a consent grant is permanent. To test reconnection, seed a second grant for the same customer_id and application_id; it is issued a new consent_id, and the original stays in the customer's history as REVOKED.

curl -X POST 'https://sandbox.plaid.com/sandbox/fdx/consent/seed' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<secret>",
    "customer_id": "consentapi-example-1",
    "application_id": "5d16db26-b759-4d3e-ab8f-e01e8c494eae"
  }'

{
  "consent_id": "9cfe04b5-6d04-45ce-897e-45f2580bf013",
  "request_id": "m8MDnv9okwxFNBV"
}

Plaid provides demo applications to grant consent to when seeding:

Seeded grants are never deleted, so repeatedly seeding and revoking the same customer_id and application_id pair grows that customer's result set from /fdx/consents indefinitely. Account for this in automated tests.

These endpoints use the FDX error format rather than Plaid's standard error object. The body contains error_type, error_code, and error_message only — there is no display_message or request_id. error_type and error_code are stable and safe to branch on; error_message is not.

A 404 deliberately does not distinguish a grant that does not exist from one belonging to another institution, so you cannot use it to probe for grants you do not own.

Because a failure here surfaces inside your own consent portal, treat these responses as internal diagnostics rather than something to pass through to the customer. A lookup that returns 404 is better rendered as an empty state than as an error.