Skip to main content
A credential represents one set of authentication details for one user on one source. 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, Deck uses the credential to authenticate a session 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. The credential is created with unverified status. It becomes verified the first time a task run successfully authenticates with it.

​
Auth methods

MethodDescription
username_passwordStandard username and password.
noneNo 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. 
{
  "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}, 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. 
{
  "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. 
{
  "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

StatusMeaning
unverifiedStored but not yet used in a successful authentication
verifiedSuccessfully authenticated at least once
invalidThe source rejected the credentials
deletedPermanently 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

Credential Vault

How Deck encrypts, stores, and deletes user credentials.

Sessions

Compute sessions created when tasks run.