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

# External IDs

> Map Deck credentials to users in your system with external identifiers.

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:

```bash theme={null}
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.

<Tabs>
  <Tab title="One user, one credential">
    The simplest pattern. Each user in your system has a single credential per source. Use your internal user ID as the `external_id`.

    ```json theme={null}
    {
      "source_id": "src_bank",
      "external_id": "user_12345",
      "auth_method": "username_password",
      "auth_credentials": { ... }
    }
    ```

    To find a user's credential later:

    ```bash theme={null}
    curl "https://api.deck.co/v2/credentials?source_id=src_bank&external_id=user_12345" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Tab>

  <Tab title="One user, multiple credentials">
    Some users may need multiple credentials to the same source (e.g., multiple bank accounts). Use a composite identifier.

    ```json theme={null}
    {
      "source_id": "src_bank",
      "external_id": "user_12345:checking",
      "auth_method": "username_password",
      "auth_credentials": { ... }
    }
    ```

    Or use your own account-level identifier:

    ```json theme={null}
    {
      "source_id": "src_bank",
      "external_id": "account_67890",
      "auth_method": "username_password",
      "auth_credentials": { ... }
    }
    ```
  </Tab>

  <Tab title="Organizational mapping">
    For B2B platforms, map credentials to organizations or teams rather than individual users.

    ```json theme={null}
    {
      "source_id": "src_payroll",
      "external_id": "org_acme_corp",
      "auth_method": "username_password",
      "auth_credentials": { ... }
    }
    ```

    This lets you query all credentials for an organization:

    ```bash theme={null}
    curl "https://api.deck.co/v2/credentials?external_id=org_acme_corp" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Tab>
</Tabs>

## Updating an external ID

You can update the `external_id` on an existing credential:

```bash theme={null}
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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/api/filtering-list-endpoints) 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.