---
title: "Create a credential"
method: POST
path: "/credentials"
tags: ["Credentials"]
---

# Create a credential

`POST /credentials`

Stores a new credential for authenticating with an external source. The credential is created immediately and can be used on task runs.

## Request body

- CreateCredentialRequest — Request body for creating a new credential.
  - `source_id` string, required — The source to authenticate against. Prefixed with `src_`.
  - `auth_method` string, nullable — Authentication method for the source. One of `username_password`, `source_fields`, or `none`. Defaults to `none` if not provided.
  - `auth_credentials` AuthCredentialsInput — Credentials payload. Structure depends on `auth_method`. For `username_password`, pass `username` and `password`. For `source_fields`, pass at least one entry in `source_fields`. Any `auth_method` except `none` may also include `source_fields` alongside its credentials (for example, `username` and `password` plus `source_fields` in the same payload), and `tokenized` to vault selected source-field values.
    - `username` string — Username for `username_password`.
    - `password` string — Password for `username_password`. Encrypted at rest and never returned.
    - `source_fields` object — Additional values the source requires at login, beyond what the `auth_method` covers (for example, `{ "company_id": "ACME-4412" }`). For the `source_fields` auth method, at least one entry is required. Values must be strings. 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 returned in the clear on read unless named in `tokenized`.
    - `tokenized` string[] — Names of `source_fields` keys to vault. Each entry must name a key present in `source_fields`. Tokenized values are stored in a secure vault, removed from API responses, and listed by name in the response `tokenized` array; they cannot be read back. On update, may only name keys supplied in the same request. Auth secrets such as `password` are always vaulted regardless of this array.
  - `external_id` string, nullable — An identifier from your system to associate with this credential. Max 255 characters. See the external IDs guide for multi-tenant patterns.
  - `persistence` PersistenceInput — Credential persistence settings. When enabled, Deck saves the credential's authenticated login state after each run and restores it on later runs. Sources that honor the restored state skip the login flow and repeat MFA prompts.
    - `enabled` boolean — Whether to save this credential's login state between runs. Defaults to `false`.

## Response `201`

Created

- CreateCredentialResponse
  - `id` string, required — Unique identifier for the credential, prefixed with `cred_`.
  - `object` string, required — Always `credential`.
  - `status` string, required — Credential status: `unverified`, `verified`, `invalid`, or `deleted`.
  - `external_id` string, nullable, required — External identifier from your system, if set.
  - `source_id` string, required — The source this credential authenticates against. Prefixed with `src_`.
  - `auth_method` string, required — Authentication method: `username_password`, `source_fields`, or `none`.
  - `auth_credentials` AuthCredentialsSummary, required — Summary of stored authentication credentials. Secret values such as `password` are encrypted at rest and never returned. Non-tokenized `source_fields` are returned in the clear; fields named in `tokenized` are vaulted and omitted from the map.
    - `username` string, nullable — The username associated with this credential, if applicable.
    - `source_fields` object — Non-tokenized `source_fields` returned as key/value pairs in the clear (for example, `{ "company_id": "ACME-4412" }`). Tokenized source fields are dropped from this map and named in `tokenized` instead. Omitted when empty.
    - `tokenized` string[] — Names of the source fields whose values were vaulted. Their values never appear in `source_fields` and cannot be read back through the API. Omitted when nothing was tokenized.
  - `persistence` PersistenceSummary, required — Persistence settings for this credential.
    - `enabled` boolean, required — Whether persistence is enabled for this credential.
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the resource was created.
  - `updated_at` string, date-time, required — ISO 8601 timestamp of when the resource was last updated.
  - `request_id` string, required — Unique identifier for the API request. Include this when contacting support.

## Other responses

- `400` — Bad request — validation error or malformed input.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found — the requested resource does not exist.
- `409` — Conflict — the request is valid but cannot be completed in the current state.
- `422` — Unprocessable content — the request body is understood but contains invalid values.
- `429` — Too many requests or session concurrency exceeded. Retry with backoff; honor Retry-After and RateLimit headers when present.
- `500` — Internal server error.

---

[API](https://skmtc.dev/deck/apis/deck-api.md) · [All operations](https://skmtc.dev/deck/apis/deck-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/deck/deck-api/revisions/eba6e2cc9351/schema)