Permissions Manager API

The Permissions Manager API reports which Plaid-powered applications one of your customers has connected, which accounts and data types each application can read, and when each application last read them. It also lets you revoke an application's access.

It is the API behind a consumer-facing consent portal on your domain: the customer sees their connections and disconnects the ones they no longer want, and Plaid enforces that revocation across the ecosystem. Single-institution accounts can read the same data with no code in the Data Partner Dashboard, whose Permissions Manager tabs call these same endpoints; this page covers the API, which is available to every integration model, including platforms.

For conceptual background on authorization records 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. 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.

Permissions Manager identifies a customer by an access_token, not by a customer identifier, so every integration starts with /item/import.

Use the same persistent, unique identifier you use as the sub claim in your OIDC ID token — see Unique user identifier (consistency key). Reusing an identifier across two customers merges their connections; changing it for an existing customer strands the connections recorded under the old one.

Because /item/import is idempotent, you can call it lazily the first time a customer opens your portal, batch it ahead of time, or call it again whenever you need the token.

curl -X POST 'https://production.plaid.com/item/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<secret>",
    "user_auth": {
      "user_id": "<user_id>"
    }
  }'

{
  "access_token": "access-sandbox-99ace160-3cf7-4e51-a083-403633425815",
  "request_id": "ewIBAn6RZirsk4W"
}

Call this each time a customer opens your portal rather than serving a cached copy, so that revocations made elsewhere in the ecosystem are reflected immediately.

The response separates applications, which the customer has authorized, from disconnected_applications, which they authorized and later revoked. Render disconnected applications as history: they carry no scopes or created_at, because there is no longer any access to describe.

Parse created_at permissively. Depending on when your integration was set up, it arrives either as an ISO 8601 datetime (2020-01-01T00:00:00Z) or as a date alone (2020-01-01).

curl -X POST 'https://production.plaid.com/item/application/list' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<secret>",
    "access_token": "<access_token>"
  }'

{}

scopes.product_access maps a data type to whether the customer authorized it. The keys that can appear are:

Only the data types an application requested appear, so treat a missing key as "not authorized" rather than as an error. Applications built on Plaid products outside this set can introduce further keys, so parse product_access as a map rather than a fixed struct.

scopes.accounts lists the customer's accounts by unique_id — the same account identifier your FDX API returns — each with whether the application may read it. new_accounts reports whether accounts the customer opens later are included automatically. An empty accounts array on a long-standing connection means the customer authorized every available account; those connections predate per-account selection.

Where you scope data types per account rather than per connection, each account also carries account_product_access, keyed by the per-account scopes configured for your integration.

/item/activity/list is the audit view of your portal: what happened to a customer's connections, and when each application last read their data. Results are paginated: pass count to size a page and the cursor from the previous response to fetch the next one. An omitted cursor in the response means you have reached the end.

curl -X POST 'https://production.plaid.com/item/activity/list' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<secret>",
    "access_token": "<access_token>"
  }'

Each entry in activities records one event. activity is the event type, initiated_date is when it happened, state is its outcome, initiator identifies who caused it, and target_application_id names the application it acted on:

last_data_access_times holds one object per application, keyed by application_id, with a timestamp for every product_access scope except bank_statements. A null timestamp means the application has never read that data type. This is the field to show a customer who wants to know whether an app they authorized months ago is still reading their accounts.

Call this endpoint as soon as a customer disconnects an application in your portal, one call per application, and never in a batch — Plaid revokes the application's access on receipt, and the delay before that call is time the application can still read data.

If you offer users the ability to revoke access, you must keep the ecosystem in sync:

1. User revokes access on your domain: The customer visits your consent portal and disconnects an application
2. Call /item/application/unlink: Your system calls Plaid's revocation endpoint
3. Plaid notifies the application: Plaid sends the application a USER_PERMISSION_REVOKED webhook
4. Plaid severs the connection: Plaid blocks the application from accessing data
5. Application stops requesting data: The application knows the customer revoked access and stops making requests

Without step 2, the application keeps its access and your portal shows a disconnection that never took effect.

A customer who wants the application again has to go through your OAuth flow from the start; there is no way to restore a revoked connection.

curl -X POST 'https://production.plaid.com/item/application/unlink' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<secret>",
    "access_token": "<access_token>",
    "application_id": "<application_id>"
  }'

{
  "request_id": "m8MDnv9okwxFNBV"
}

Plaid can optionally send webhooks to you when authorization events occur. They are independent of which API you read with. Single-institution accounts can configure them 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. For the payload shape and full examples, see Webhooks on the Consent API reference.

Notifies you every time a customer connects a new application 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 customer never goes through your OAuth flow and this webhook is your only real-time signal that a new connection was created.

When it fires: After a customer successfully authorizes a new application.

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

What to do: Record the new connection. The webhook identifies the customer and the application, but not the accounts or data types they authorized, so treat it as a signal to call /item/application/list for the full set of scopes. If you offer a consent portal, display this new connection so customers can view and manage it.

Notifies you when a customer revokes an application's access, either through the application 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 customers disconnect through my.plaid.com or the application itself instead of through you.

When it fires: After a customer or application revokes authorization.

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

What to do: Mark the connection revoked in your own records and update your portal. Revocations that happen in Plaid Portal or in the application itself also land in /item/activity/list as PORTAL_UNLINK and ITEM_REMOVE entries.

• Call /item/application/unlink as soon as a customer disconnects an application, to keep the ecosystem in sync during revocations
• Implement the CONSENT_REVOKED webhook if you offer a consent portal
• Set refresh token expiration to 13+ months (allows buffer for reauthorization)
• Direct users to my.plaid.com for self-service connection management

Point the same calls at sandbox.plaid.com with your Sandbox secret. /item/import returns a working Sandbox access token, and /item/application/list and /item/activity/list return fixture data for demo applications, so you can build and test your portal's rendering before you have live connections.

That fixture data is static: unlinking a demo application does not change what /item/application/list returns. To exercise the state changes instead, use dynamic Sandbox, which is enabled for most clients: connect a demo app, see it appear in /item/application/list, unlink it, and see it move to disconnected_applications. /sandbox/item/application/seed connects a demo application to a customer, standing in for a customer completing your OAuth flow. If it returns 403 SANDBOX_SEEDING_NOT_ENABLED, dynamic Sandbox is off for your client — ask your Plaid solutions engineering team to enable it. /item/activity/list always serves its fixture in Sandbox, dynamic Sandbox or not, so you can build your portal's activity view against it, but you won't see real activity until Production.

curl -X POST 'https://sandbox.plaid.com/sandbox/item/application/seed' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client_id>",
    "secret": "<sandbox_secret>",
    "access_token": "<access_token>",
    "application_id": "5cfef3f0-e405-4597-991d-057ac558e3d5"
  }'

{
  "item_id": "9xGbdRaG3gianaxoELGpILQ7drV3RnclMGdKJ",
  "request_id": "m8MDnv9okwxFNBV"
}

Plaid provides three demo applications to connect:

These endpoints return Plaid's standard error object (error_type, error_code, error_message, display_message, request_id). Log request_id when you encounter an error to speed up troubleshooting with Plaid.

A customer with no connections is a normal state, not a failure: /item/application/list returns 200 with an empty applications array. If you integrated before February 2022, you may receive 404 NO_CONNECTED_APPLICATIONS instead; render either as an empty portal.

Unlinking an application whose access has already ended returns 204 with APPLICATION_ALREADY_UNLINKED. Treat it as success — the revocation you asked for is already in effect — which makes retries safe.