> ## 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, such as a `company_id` or `account_number` 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.
By default, source field values are non-secret context and are readable on read. When you retrieve a credential with [`GET /credentials/{credential_id}`](/api-reference/credentials/retrieve-a-credential), or list credentials, the response returns `source_fields` as a map of the stored key/value pairs, so you can read back any value you saved without tokenizing it. Use this for non-sensitive identifiers like `company_id`. To vault a value instead of returning it, declare it in `tokenized` (below); tokenized values are never returned this way and appear only by name in the `tokenized` array. At task run time, the agent resolves each entry by key (for example, `{{credential.company_id}}`) into the login flow.
### Tokenizing source fields
Available on Enterprise plans.
Some source fields hold sensitive values, such as a social security number, that should never sit in plaintext or appear in API responses. Declare those fields in a `tokenized` array inside `auth_credentials`. Each entry must name a key present in `source_fields`. This mirrors [tokenizing task inputs](/concepts/tasks#tokenizing-sensitive-fields).
```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",
"member_ssn": "123-45-6789"
},
"tokenized": ["member_ssn"]
}
}
```
Here `member_ssn` is vaulted and `company_id` is stored in the clear. Deck tokenizes the declared values when the credential is written, storing them in a secure vault, and restores them at dispatch so the agent can use them on the source.
Tokenizing a field is more secure, since the value is vaulted and never exposed through the API. The tradeoff is that you can't query it back: tokenized fields are removed from `source_fields` entirely and only their names appear in the `tokenized` array, whereas non-tokenized fields are returned in the clear and can be read back when you retrieve the credential. The full set of fields is the union of the `source_fields` keys and `tokenized`, and `tokenized` is omitted when nothing was vaulted.
```json theme={null}
{
"credential_id": "cred_01ABC...",
"auth_method": "username_password",
"auth_credentials": {
"username": "mark@example.com",
"source_fields": {
"company_id": "ACME-4412"
},
"tokenized": ["member_ssn"]
}
}
```
Auth secrets like `password` are always vaulted regardless of `tokenized`. The array governs source fields only.
When you update a credential, only the fields you include change. Within `source_fields`, a supplied value upserts that key and an explicit `null` deletes it along with its vault token. On update, `tokenized` may only name keys you supply in the same request. Because tokenized values are never readable back through the API, changing a field's tokenization status requires re-supplying its value; fields you omit keep both their value and their current tokenization status.
## 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
How Deck encrypts, stores, and deletes user credentials.
Compute sessions created when tasks run.