External IDs - Deck Docs

The external_id field on credentials lets you associate a Deck resource with an identifier from your own system. This is the primary mechanism for mapping Deck credentials to your users, accounts, or tenants.

How it works

When you create a credential, pass an external_id to link it to a record in your system:

curl -X POST "https://api.deck.co/v2/credentials" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc",
    "external_id": "user_12345",
    "auth_method": "username_password",
    "auth_credentials": {
      "username": "...",
      "password": "..."
    }
  }'

The external_id is stored on the credential and returned in all API responses and event payloads for that credential.

Constraints

Maximum length: 255 characters
Must be a string
Can be null (no external mapping)
Not required to be unique across credentials, but in most cases you’ll want it to be meaningful

Multi-tenant patterns

If you’re building a platform where multiple end users connect to the same source, external_id is how you keep track of which credential belongs to which user.

One user, one credential
One user, multiple credentials
Organizational mapping

The simplest pattern. Each user in your system has a single credential per source. Use your internal user ID as the external_id.

{
  "source_id": "src_bank",
  "external_id": "user_12345",
  "auth_method": "username_password",
  "auth_credentials": { ... }
}

To find a user’s credential later:

curl "https://api.deck.co/v2/credentials?source_id=src_bank&external_id=user_12345" \
  -H "Authorization: Bearer sk_live_..."

Some users may need multiple credentials to the same source (e.g., multiple bank accounts). Use a composite identifier.

{
  "source_id": "src_bank",
  "external_id": "user_12345:checking",
  "auth_method": "username_password",
  "auth_credentials": { ... }
}

Or use your own account-level identifier:

{
  "source_id": "src_bank",
  "external_id": "account_67890",
  "auth_method": "username_password",
  "auth_credentials": { ... }
}

For B2B platforms, map credentials to organizations or teams rather than individual users.

{
  "source_id": "src_payroll",
  "external_id": "org_acme_corp",
  "auth_method": "username_password",
  "auth_credentials": { ... }
}

This lets you query all credentials for an organization:

curl "https://api.deck.co/v2/credentials?external_id=org_acme_corp" \
  -H "Authorization: Bearer sk_live_..."

Updating an external ID

You can update the external_id on an existing credential:

curl -X PATCH "https://api.deck.co/v2/credentials/{credential_id}" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "new_user_id"
  }'

Set it to null to remove the mapping:

{
  "external_id": null
}

External IDs in events

When a credential triggers an event (e.g., credential.verified), the event payload includes the credential’s external_id. This lets you route event processing to the right user in your system without an extra API call.

{
  "id": "evt_abc",
  "type": "credential.verified",
  "data": {
    "id": "cred_def",
    "object": "credential",
    "external_id": "user_12345",
    "status": "verified"
  }
}

Use this to look up the user in your database and take action (send a notification, update a record, trigger a downstream process) without needing to call GET /v2/credentials/{credential_id}.

Best practices

Set external_id at creation time. It’s easier to set it upfront than to backfill later.
Use stable identifiers. Choose IDs that won’t change, like your database primary key or a UUID. Avoid using emails or usernames that users can modify.
Keep it consistent. Use the same external_id format across all credentials for a given user. If you use user_12345 for one source, use it for all sources.
Use it for filtering. The list credentials endpoint supports filtering by external_id, making it easy to find all credentials for a specific user. You can also search by external_id in the Console.

​How it works

​Constraints

​Multi-tenant patterns

​Updating an external ID

​External IDs in events

​Best practices