Consent API (beta)

Use the Consent API 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.

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.

For conceptual background on authorization records, or to learn how to manage consent via the Dashboard instead of via API, see Consent management.

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.

If you offer users the ability to revoke access to connected apps (for example, via a consumer-facing consent portal), you must keep the ecosystem in sync. When a user revokes access on your side, Plaid and the downstream app need to know immediately.

How it works:

1. User revokes access on your domain: User visits your consent portal and disconnects an app
2. Call PUT /fdx/consents/{consentId}/revocation: Your system calls Plaid's revocation endpoint
3. Plaid notifies the app: Plaid sends a webhook to the disconnected app
4. Plaid severs the connection: Plaid blocks the app from accessing data
5. App stops requesting data: The app knows the user revoked access and stops making requests

This keeps revocation instant across all parties. Without it, the app won't know that consent has been revoked until the next time it attempts to actively fetch data from the connection.

Plaid notifies you of these events in real time via webhooks; see Webhooks below.

Plaid can optionally send webhooks to you when authorization events occur. Single-institution accounts can configure these in the Data Partner Dashboard via the Developers > Webhooks page. Platform accounts should reach out to your Plaid contact to have these enabled.

Plaid sends two webhooks: AUTHORIZATION_GRANTED and CONSENT_REVOKED.

Each webhook is an FDX event notification: a category/type pair identifies the event, and notificationPayload.customFields carries the details as name/value pairs.

Notifies you every time a user connects a new app via Plaid. While your system will already know about new OAuth authorizations, this webhook also alerts you to connections created via the returning user experience, where the user doesn't go through your OAuth flow and this webhook is your only real-time signal that a new connection was created.

When it fires: After a user successfully authorizes a new app.

Payload includes: The customer (user_identifier) and app details (application_id, application_name).

What to do: Record the new connection. The webhook identifies the user and the app, but not the accounts or data clusters they authorized, so treat it as a signal to fetch the full consent grant from GET /fdx/consents rather than as the authorization record itself. If you offer a consent portal, display this new connection so users can view and manage it.

{
  "notificationId": "b3f1c4d2-8a5e-4b6a-9c1f-2e7d5a8b3c9d",
  "sentOn": "2026-08-05T14:32:00Z",
  "category": "AUTHORIZATION",
  "type": "AUTHORIZATION_GRANTED",
  "publisher": { "name": "Plaid", "type": "DATA_ACCESS_PLATFORM" },
  "notificationPayload": {
    "id": "consentapi-example-1",
    "idType": "CONSENT",
    "customFields": [
      { "name": "user_identifier", "value": "consentapi-example-1" },
      { "name": "application_id", "value": "09f9befa-acb6-4575-93c7-b64ef523641e" },
      { "name": "application_name", "value": "Incremental Investing" }
    ]
  }
}

Notifies you when a user revokes access to an app, either through the third-party app itself or via my.plaid.com (Plaid Portal). If you offer a consent portal, you need this webhook to catch the revocations that happen elsewhere; otherwise your portal will drift out of sync when users disconnect through my.plaid.com or the app itself instead of through you.

When it fires: After a user or app revokes authorization.

Payload includes: The customer (user_identifier), app details, and who initiated the revocation (initiator: DATA_ACCESS_PLATFORM, INDIVIDUAL, or DATA_RECIPIENT).

What to do: Update your authorization records to mark the connection as revoked. If you offer a consent portal, update the display to show that the connection is no longer active.

{
  "notificationId": "e7a2d9f1-3b6c-4a8e-9d5f-1c8b4e2a7d3f",
  "sentOn": "2026-08-05T14:35:00Z",
  "category": "CONSENT",
  "type": "CONSENT_REVOKED",
  "publisher": { "name": "Plaid", "type": "DATA_ACCESS_PLATFORM" },
  "notificationPayload": {
    "id": "consentapi-example-1",
    "idType": "CONSENT",
    "customFields": [
      { "name": "user_identifier", "value": "consentapi-example-1" },
      { "name": "application_id", "value": "09f9befa-acb6-4575-93c7-b64ef523641e" },
      { "name": "application_name", "value": "Incremental Investing" },
      { "name": "initiator", "value": "INDIVIDUAL" }
    ]
  }
}

• Implement the CONSENT_REVOKED webhook if you offer a consent portal
• Use PUT /fdx/consents/{consentId}/revocation to keep the ecosystem in sync during revocations
• Set refresh token expiration to 13+ months (allows buffer for reauthorization)
• Direct users to my.plaid.com for self-service connection 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.

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.

The two APIs describe the same underlying consent in different schemas.

The two views describe the same underlying consent, and revoking through either one takes effect everywhere.

Permissions Manager identifies a customer by an access_token, so every call is preceded by exchanging a customer identifier for one via /item/import. The Consent API drops this step: every endpoint takes your customerId directly, the same persistent identifier you use as the sub claim in your OIDC ID token. If you migrate, you can remove the /item/import call from your integration entirely.

Permissions Manager reports scopes as product_access keys; the Consent API reports the same access as FDX data clusters. The two taxonomies don't line up one to one — for example, account_balance_info spans both ACCOUNT_BASIC and BALANCES:

This mapping is derived from each field's description in the two schemas, not from a joint spec. Confirm it with your Plaid solutions engineering team before relying on it for scope-gated logic.

Permissions Manager returns Plaid's standard error object (error_type, error_code, error_message, display_message, request_id). The Consent API uses the FDX error format instead — only error_type, error_code, and error_message, with no display_message or request_id — so error-handling code written against Permissions Manager will need updating rather than reused as-is. See Errors above for the full list.