Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.deck.co/llms.txt

Use this file to discover all available pages before exploring further.

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.
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_..."

​
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.