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

# Credentials

> A credential stores authentication details for a user on a source.

A credential represents one set of authentication details for one user on one [source](/concepts/sources). If a user needs access to Hilton and Marriott, that's two credentials. Use `external_id` when creating credentials to tie them back to users in your system.

## How credentials fit in

A credential stores the auth details Deck needs to log in on behalf of a user. When you [run a task](/concepts/task-runs), Deck uses the credential to authenticate a [session](/concepts/sessions) against the source. You don't need to manage sessions or track login state. Just store the credential and run tasks against it.

Credentials are optional on tasks. There are two cases where you would use credentials:

* **Working with sources that require authentication.** Store your own credentials or your user's credentials in the credential vault and securely pass them to run a task.
* **Linking users in your system to Deck.** You can use credentials to link users to your system with an `external_id` and pass the `auth_method` as `none`. This provides user linking without credential storage.

## Creating a credential

Pass authentication details through the API. Deck encrypts and stores them in the [credential vault](/platform/credential-management).

The credential is created with `unverified` status. It becomes `verified` the first time a task run successfully authenticates with it.

## Auth methods

| Method              | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `username_password` | Standard username and password.                                                  |
| `none`              | No credentials needed (public sources). Use this to link users from your system. |

## Source fields

Some sources require additional values beyond what the `auth_method` covers — for example, a `company_id` or `tenant_id` that sits alongside a username and password at login. Pass these values through `source_fields` inside `auth_credentials`.

`source_fields` composes with any `auth_method`. The source dictates which keys it requires; you supply the values.

```json theme={null}
{
  "source_id": "src_01HXYZ...",
  "auth_method": "username_password",
  "auth_credentials": {
    "username": "mark@example.com",
    "password": "hunter2",
    "source_fields": {
      "company_id": "ACME-4412"
    }
  },
  "external_id": "cust_42"
}
```

Keys must match `^[a-z][a-z0-9_]{0,63}$`, must not collide with reserved keys on the `auth_method` (such as `username` or `password`), and are capped at 10 entries per credential.

Values are encrypted at rest using the same envelope as other secret credential fields, and are redacted on read — they never appear in API responses. At task run time, the agent harness resolves each entry by key (for example, `{{credential.company_id}}`) into the login flow.

## Credential statuses

| Status       | Meaning                                                        |
| ------------ | -------------------------------------------------------------- |
| `unverified` | Stored but not yet used in a successful authentication         |
| `verified`   | Successfully authenticated at least once                       |
| `invalid`    | The source rejected the credentials                            |
| `deleted`    | Permanently removed from the credential vault, still queryable |

A credential becomes `verified` when a task run authenticates with it successfully. This happens automatically.

A credential becomes `invalid` when the source rejects the stored credentials. This can happen when a password is changed on the source or the account is locked. To fix it, update the credential with correct details.

A `deleted` credential has been permanently removed from the credential vault. The credential object and its associated task runs are still queryable, but no new tasks can use it.

## Deep dives

<CardGroup cols={2}>
  <Card title="Credential Vault" icon="vault" href="/platform/credential-management">
    How Deck encrypts, stores, and deletes user credentials.
  </Card>

  <Card title="Sessions" icon="display" href="/concepts/sessions">
    Compute sessions created when tasks run.
  </Card>
</CardGroup>