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.

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 — 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. 
{
  "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

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.