Credentials - Crewship

The credential vault is Crewship’s encrypted store for API keys, OAuth tokens, and secrets. It covers the full lifecycle: CRUD on credentials, live validation (test before save and re-test stored values), zero-downtime rotation with a configurable grace window, an append-only audit timeline, and per-agent assignment. Values are protected at rest with AES-256-GCM and are never returned in API responses.

All credential endpoints require authentication and workspace context unless otherwise noted.

Endpoints

Credential endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/credentials`	List credentials with assignment info
`POST`	`/api/v1/credentials`	Create a credential
`GET`	`/api/v1/credentials/{credentialId}`	Get credential metadata
`PATCH` `PUT`	`/api/v1/credentials/{credentialId}`	Partial-update a credential
`DELETE`	`/api/v1/credentials/{credentialId}`	Soft-delete a credential
`POST`	`/api/v1/credentials/test`	Validate a value without storing it
`POST`	`/api/v1/credentials/{credentialId}/test`	Re-test a stored credential
`POST`	`/api/v1/credentials/{credentialId}/refresh`	Refresh a provider login’s access token now
`GET`	`/api/v1/credentials/{credentialId}/audit`	Read the credential audit timeline
`POST`	`/api/v1/credentials/{credentialId}/rotate`	Rotate with grace overlap
`GET`	`/api/v1/credentials/{credentialId}/rotations`	List rotation history
`DELETE`	`/api/v1/credential-rotations/{rotationId}`	End a grace window early
`GET`	`/api/v1/credentials/bindings`	List (scope, slot) → credential bindings
`POST`	`/api/v1/credentials/bindings`	Bind a credential to a slot in one scope
`DELETE`	`/api/v1/credentials/bindings/{bindingId}`	Remove a binding
`GET`	`/api/v1/agents/{agentId}/credential-bindings`	Resolved slot map for one agent
`GET`	`/api/v1/credentials/default-env-var`	Default env var name for a provider
`POST`	`/api/v1/credentials/{credentialId}/reveal`	Disclose a value in plaintext (heavily gated)
`GET`	`/api/v1/credentials/{credentialId}/fields`	List a credential’s custom fields (secret values omitted)
`POST`	`/api/v1/credentials/{credentialId}/fields`	Add a field
`PUT`	`/api/v1/credentials/{credentialId}/fields/{fieldKey}`	Update a field
`DELETE`	`/api/v1/credentials/{credentialId}/fields/{fieldKey}`	Delete a field
`GET`	`/api/v1/credentials/reveal-policy`	Read the workspace reveal switch
`GET`	`/api/v1/credentials/{credentialId}/access/me`	Explain your own access to a visible credential; hidden rows answer 404 and no secret is returned
`PUT`	`/api/v1/credentials/reveal-policy`	Turn the workspace reveal switch on or off
`PUT`	`/api/v1/credentials/{credentialId}/sensitivity`	Set a credential’s classification
`POST`	`/api/v1/provider-logins/device`	Start a device-code sign-in to a model provider
`GET`	`/api/v1/provider-logins/device/{deviceId}`	Status of a device-code sign-in
`GET`	`/api/v1/provider-logins/pools`	List provider pools (account groups)
`POST`	`/api/v1/provider-logins/pools`	Create a provider pool
`GET`	`/api/v1/provider-logins/pools/{poolId}`	Read one pool with its members and ETag
`PUT`	`/api/v1/provider-logins/pools/{poolId}`	Replace a pool definition (`If-Match`)
`DELETE`	`/api/v1/provider-logins/pools/{poolId}`	Retire a pool definition (`If-Match`)

Endpoint contract

Each endpoint identifies Auth, Request, Response, and Status. Unless noted, requests and responses are JSON, workspace routes require a session/CLI token plus membership, and secret values are never returned. The shared failures are 401 unauthenticated, 403 unauthorized, 400 invalid input, 404 missing or invisible resource, 409 uniqueness/lifecycle conflict, and 500 unexpected handler/database failure. Test and reveal routes may also return 429. Route gates and status writes are verified in internal/api/router_crews.go, internal/api/credentials_mutate.go, internal/api/credential_rotation.go, and internal/api/credential_fields.go. Auth: Use the role/capability written on the endpoint; read visibility is also enforced for crew-scoped credentials. Request: JSON body and query parameters are shown on the endpoint. Secret values may be sent only to create, rotate, test, or reveal operations. Response: Credential metadata, rotation records, bindings, and field metadata never contain the encrypted credential value; reveal is the sole explicit exception and is separately audited. Status: Success is 200 for reads/updates, 201 for creates, and 204 where a delete section says so. Invalid input is 400, authorization is 401 or 403, invisible resources are 404, conflicts are 409, and rate limits are 429.

Managing Credentials

Explain your credential access

GET /api/v1/credentials/{credentialId}/access/me

Auth: Session or CLI token with membership in the selected workspace. The credential must pass the same visibility filter as the detail endpoint. Request: Path credential ID and required workspace_id query; no body. Response: credential_id and actions, each with state (allowed, conditional, or denied) and reason. reveal can only be conditional: fresh interactive login, a written reason and a successful audit write are checked by the reveal action. A CLI token receives non_interactive_auth. No secret value is read or returned by this endpoint. Status: 200 for a visible credential, 401 without authentication, 404 for a missing or hidden credential, and 500 if a policy or capability lookup fails. The response is not cached.

Routine dependents

GET /api/v1/credentials/{credentialId}/dependents returns visible, saved routines that statically declare the credential’s type through credentials_required, credential_ref.type, or {{ secrets.<type> }} in supported steps and hooks. Each row has a routine slug, name, type, and resolution: would_resolve if the runtime’s current ACTIVE selection points to this credential, another_credential if a different matching row wins, or unavailable if no row qualifies. The response also includes visibility_limited, dynamic_uses_untracked, and recorded_use: "not_attributed". It never returns secret values. These are configured references and a present-time selection estimate, not a run-level usage record. Agent and script lookups performed dynamically cannot be inferred from the routine definition. Hidden routines are excluded for non-management roles. Selection follows the runtime’s credential_crews grants for any live crew, with an unlinked workspace credential as fallback; legacy crew_id alone does not grant access. crewship credential dependents <name-or-id> shows the same view in the CLI. Core CRUD for the vault — create, read, update, and soft-delete credential records. Secret values are encrypted on write and omitted from every response.

List Credentials

GET /api/v1/credentials?workspace_id={workspaceId}

Returns all credentials in the workspace with agent assignment info. Auth: Session or CLI token + workspace membership. Provider accounts are OWNER/ADMIN-only: a PROVIDER_LOGIN row, and an AI_CLI_TOKEN / API_KEY row whose provider is a model provider, is dropped from the list for every lower role (credentialVisibilityFilter in internal/api/credentials_loaders.go), and any per-id route answers 404 for it below OWNER/ADMIN (providerAccountPolicy in internal/api/provider_login_policy.go) — a capability grant for ordinary secrets does not cross this boundary. Delivery to agents is unchanged. Query Parameters: (parseListPagination in internal/api/credentials.go:81)

Parameter	Type	Default	Description
`workspace_id`	string	—	Required workspace context.
`limit`	integer	`100`	Page size. Capped at `500`; values `<= 0` fall back to the default.
`offset`	integer	`0`	Row offset for pagination. Negative values clamp to `0`.
`q`	string	—	Server-side substring search on name and description (`search` is the older spelling of the same filter).
`tag`	string	—	Exact tag filter.
`kind`	string	—	`provider_login`: only rows that carry a `login` object — `PROVIDER_LOGIN` rows and `AI_CLI_TOKEN` / `API_KEY` rows whose provider is `ANTHROPIC`, `OPENAI`, `GOOGLE`, `CURSOR`, `FACTORY`, `XAI`, `GROQ`, `OPENROUTER`, `DEEPSEEK`, `MOONSHOT`, `ZAI`, `MINIMAX`, `OPENCODE`, `OPENCODE_GO` or `ZAI_CODING_PLAN`. Any other value is `400`. Works with `paginate=true` too.

The response carries X-Total-Count, X-Limit and X-Offset describing the window (see Paging under List Crews); the cursor form below carries X-Total-Count and X-Limit too. Ordering is type ASC, created_at DESC, id ASC, so paging with limit/offset is stable across requests. Pass paginate=true to use the opt-in cursor form instead of the legacy array. That form defaults to limit=50, caps limit at 500, orders by created_at DESC, id DESC, and returns { "credentials": [...], "next_cursor": "...", "limit": 50 }; next_cursor is null on the last page. A malformed cursor or a non-positive limit in this mode returns 400. Response: 200 OK

[
  {
    "id": "cred_abc",
    "name": "anthropic-primary",
    "description": "Main Anthropic API key",
    "type": "AI_CLI_TOKEN",
    "provider": "ANTHROPIC",
    "status": "ACTIVE",
    "scope": "WORKSPACE",
    "crew_id": null,
    "crew_ids": [],
    "account_label": "Production",
    "account_email": "team@company.com",
    "token_expires_at": "2025-12-31T00:00:00Z",
    "last_checked_at": "2024-01-15T10:00:00Z",
    "last_error": null,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "_count_agent_credentials": 5,
    "agent_names": ["Backend Dev", "Frontend Dev", "QA Engineer"],
    "mcp_used": false
  }
]

Response Fields

Field	Type	Description
`id`	string	Credential ID
`name`	string	Display name
`description`	string?	Description
`type`	string	Credential type
`provider`	string	Provider identifier
`status`	string	Current status: `ACTIVE`, `PENDING`, `PENDING_APPROVAL`, `REQUESTED`, `RATE_LIMITED`, `EXPIRED`, `REVOKED` or `ERROR` (see Statuses)
`scope`	string	`WORKSPACE` or `CREW`
`crew_id`	string?	Legacy single crew ID
`crew_ids`	string[]	All associated crew IDs
`account_label`	string?	Account label
`account_email`	string?	Account email
`token_expires_at`	string?	Token expiry timestamp
`last_checked_at`	string?	Last health check timestamp
`last_error`	string?	Last error message
`_count_agent_credentials`	integer	Number of agent assignments
`agent_names`	string[]	Names of assigned agents
`mcp_used`	boolean	Whether used by MCP bindings
`endpoint_url`	string?	Base URL echoed only for `ENDPOINT_URL` credentials; secret auth fields are never returned
`testable`	boolean	Whether a real provider probe is available for this credential
`sensitivity`	string	Reveal classification: `STANDARD`, `RESTRICTED`, or `SEALED`
`security_level`	integer	Keeper security tier, `1` through `4`
`security_level_label`	string	Operator-facing label for the security tier
`username`	string?	USERPASS cleartext identifier (null for all other types)
`last_used_at`	string?	Latest USE event recorded by the audit timeline
`last_used_ips`	string[]	Ring-buffer (max 5) of recent caller IPs
`tags`	string[]	Free-form tag labels (always non-null in JSON)
`created_by_actor_type`	string?	Attribution (v98): `user`, `agent`, or `system`
`created_by_actor_id`	string?	Attribution (v98): the actor id, `null` for `system` rows
`provisioned_for_service`	string?	`<crew>/<service>` tag for Crewship-managed (AUTO_MANAGED) rows; `null` otherwise
`login`	object?	Present only on a provider login (`PROVIDER_LOGIN`, or `AI_CLI_TOKEN` / `API_KEY` of a model provider): `mode` (`subscription` \| `api_key`), `provider`, `plan` / `plan_label` (string or `null`), `owner_user_id` / `owner_email`, `expires_at` (`null` = unknown or never), `refresh` (`supported`, `status` ∈ `ok` \| `pending` \| `failed` \| `needs_relogin` \| `none`, `last_at`, `next_at`, `error`), `quota` (`null` until seat quotas land), `delivery` (`kind` ∈ `env` \| `file`, `target`), `pays_for` (`agents`, `crews` — distinct agents and crews reached through grants and bindings). Legacy rows carry it derived: mode from the type, plan and expiry from the token where it says, `refresh.supported = false`.
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Create Credential

POST /api/v1/credentials?workspace_id={workspaceId}

Auth: MANAGER+ role, or a member with the credential.create capability for this workspace. A provider account (type: PROVIDER_LOGIN, or AI_CLI_TOKEN / API_KEY with a model provider) needs OWNER or ADMIN; below that the request is 403 Provider accounts require OWNER or ADMIN, and the credential.create capability does not lift it. Request Body:

Field	Type	Required	Default	Description
`name`	string	Yes	—	Display name (1-255 characters)
`value`	string	Conditional	—	Secret value (required unless type is `OAUTH2`, or `pending = true`). Max 64 KiB (`ENDPOINT_URL` values are capped at 2048 bytes).
`description`	string	No	`null`	Description
`type`	string	No	`"SECRET"`	Credential type
`provider`	string	No	`"NONE"`	Provider identifier
`scope`	string	No	`"WORKSPACE"`	`"WORKSPACE"` or `"CREW"`
`crew_id`	string	No	`null`	Legacy single crew ID
`crew_ids`	string[]	No	`[]`	Associated crew IDs (auto-sets scope to `CREW`)
`tags`	string[]	No	`[]`	Free-form tag labels
`account_label`	string	No	`null`	Account label
`account_email`	string	No	`null`	Account email
`username`	string	No	`null`	Cleartext identifier half of `USERPASS` credentials (required when type is `USERPASS`)
`token_expires_at`	string	No	`null`	Token expiry timestamp
`security_level`	integer	No	`1`	Security level (1-4)
`refresh_token`	string	No	`null`	OAuth refresh token. Max 64 KiB.
`oauth_client_id`	string	No	`null`	OAuth client ID (OAUTH2 type only)
`oauth_client_secret`	string	No	`null`	OAuth client secret
`oauth_auth_url`	string	No	`null`	OAuth authorization URL
`oauth_token_url`	string	No	`null`	OAuth token URL
`oauth_scopes`	string	No	`null`	OAuth scopes (space-separated)
`pending`	boolean	No	`false`	Create a placeholder credential (status `PENDING`, no real value) used by `crewship apply -f` manifest slots

{
  "name": "anthropic-primary",
  "type": "AI_CLI_TOKEN",
  "provider": "ANTHROPIC",
  "value": "sk-ant-api03-xxxxx",
  "scope": "WORKSPACE",
  "description": "Main Anthropic API key"
}

The value is encrypted with AES-256-GCM before storage using the format v1:{base64(IV||AuthTag||Ciphertext)}. Response: 201 Created — credential object (without the encrypted value).

Status	Condition
`400`	Missing name, missing value (non-OAuth2), invalid crew_id, invalid type/USERPASS without username
`403`	Insufficient role (requires MANAGER, ADMIN, or OWNER; OWNER or ADMIN for a provider account)
`409`	Credential with this name already exists in the workspace

Get Credential

GET /api/v1/credentials/{credentialId}?workspace_id={workspaceId}

Returns credential metadata (never the encrypted value). Response: 200 OK — credential object with crew_ids, agent_names, and mcp_used.

Status	Condition
`404`	Credential not found

Update Credential

PATCH /api/v1/credentials/{credentialId}?workspace_id={workspaceId}
PUT /api/v1/credentials/{credentialId}?workspace_id={workspaceId}

Both methods behave as partial update. Auth: OWNER, ADMIN, or MANAGER role (canRole(role, "update") in internal/api/credentials_mutate.go). A MANAGER cannot reach a provider account at all — the row is 404 for them (see List). Updatable Fields:

Field	Type	Description
`name`	string	Display name
`description`	string	Description
`value`	string	New secret value (re-encrypted; resets status to ACTIVE and records an inline-rotate audit event). Max 64 KiB. On a `PROVIDER_LOGIN` this is a re-login — see below.
`mode`	string	`PROVIDER_LOGIN` re-login only: `subscription` or `api_key`. Inferred from the value’s shape when omitted, exactly as on create. Ignored for every other type.
`type`	string	Credential type
`provider`	string	Provider identifier. Folded onto its canonical spelling when it names a recognised provider (`openai_compat` → `OPENAI_COMPAT`), stored verbatim otherwise — the column has never been a closed enum.
`scope`	string	`WORKSPACE` or `CREW`
`crew_id`	string	Legacy single crew ID
`crew_ids`	string[]	Associated crew IDs (replaces existing)
`tags`	string[]	Free-form tag labels (empty array / null clears the column)
`account_label`	string	Account label
`account_email`	string	Account email
`username`	string	USERPASS cleartext identifier
`token_expires_at`	string	Token expiry timestamp
`security_level`	integer	Security level (1-4)

Note: The status field cannot be updated via this endpoint. Status changes are managed by the credential monitor and OAuth refresh worker. Re-login (PROVIDER_LOGIN with value). Sending a value to a provider login replaces the login in place, keeping the credential’s id and every assignment and binding: the value is split into its parts again (access token, refresh token, id token, account, plan, expiry) the way create splits it, the previous parts and the refresh state (provider_login_refresh) are discarded, and token_expires_at is taken from the new token. type and provider must stay what they are — a request that changes either alongside value is 400 re-login must keep the existing provider and type. This is how a login that reached needs_relogin is brought back without re-granting it.

Changing provider to or from OPENAI_COMPAT requires sending value in the same request, and returns 400 otherwise.For most providers the stored value is an opaque token. For a provider whose upstream comes from the credential it is a {"baseURL", "apiKey", "headers"} object that Crewship splits before delivery. Switching between the two re-interprets bytes that are already stored: one direction leaves a bare key under a loader that expects an object (the credential saves and then silently reaches no agent), the other leaves an object under a loader that expects a key — which would send the base URL and every custom header upstream in an Authorization header. Crewship refuses rather than guess a conversion.

Response: 200 OK — updated credential object.

Status	Condition
`400`	No fields to update, invalid crew_id, `security_level` outside 1–4
`400`	`PROVIDER_LOGIN` re-login: `value` sent together with a different `type` or `provider` (`re-login must keep the existing provider and type`), or a value the provider’s login parser rejects (a bare token where an `auth.json` is expected, an unknown `mode`)
`403`	Insufficient role
`404`	Credential not found — including a provider account below OWNER/ADMIN

Delete Credential

DELETE /api/v1/credentials/{credentialId}?workspace_id={workspaceId}

Soft-deletes the credential and clears it from all MCP bindings.

Deleting a credential removes it from every MCP binding that references it.

Auth: OWNER or ADMIN role Response: 200 OK

{
  "success": true
}

Status	Condition
`403`	Insufficient role
`404`	Credential not found

Validating Credentials

Probe a value against the provider’s live API — either an unsaved value before storing it, or an existing stored credential.

Test Credential

POST /api/v1/credentials/test

Validates a credential value against the provider’s API without storing it. Useful for checking a key before saving. Rate-limited to 60 requests/minute per IP. Auth: Session or CLI token (no workspace context needed) Request Body: (internal/api/credentials_test_endpoint.go:229)

Field	Type	Required	Description
`provider`	string	No	Provider to test against (drives which API is probed)
`type`	string	No	Credential type (used to special-case Anthropic OAuth tokens)
`value`	string	Yes	Value to test

{
  "provider": "ANTHROPIC",
  "type": "AI_CLI_TOKEN",
  "value": "sk-ant-api03-xxxxx"
}

Response: 200 OK with { "valid": bool, "status": int, "error": string | null, "supported": bool }. error carries omitempty, so on a clean probe the key is absent rather than empty or null. The generated spec declares it nullable: true, so a generated client may also admit null; treat absent, "" and null as the same “no error”. Read supported and valid, not the presence of error. supported reports whether this credential shape has a probe, not whether an upstream request was dialled on this route. For OPENAI_COMPAT and for any ENDPOINT_URL it answers true while this route validates only that the URL is well-formed — the reachability dial is withheld here on purpose. See the note under Test Stored Credential below. For type: PROVIDER_LOGIN, an optional mode (api_key or subscription) selects the credential shape; when omitted, Crewship infers it from the value. Only api_key mode uses the provider’s API-key probe.

Test Stored Credential

POST /api/v1/credentials/{credentialId}/test

Re-tests an already-stored credential by decrypting its value server-side and probing the provider. Records an audit event so the detail-sheet timeline reflects the manual check. (internal/api/credentials_test_endpoint.go:253) Auth: OWNER, ADMIN, or MANAGER role (canRole(role, "update")). Rate-limited to 60 requests/minute per IP. Response: 200 OK with { "valid": bool, "status": int, "error": string | null, "supported": bool }. supported reports whether this stored credential has a real upstream probe. Crewship maintains probes for API-key credentials from ANTHROPIC, OPENAI, OPENAI_COMPAT, GOOGLE, OPENROUTER, CURSOR, FACTORY, GITHUB, GITLAB and VERCEL (probeSupportedProviders in internal/api/credentials_test_endpoint.go), plus any credential of type ENDPOINT_URL whatever its provider — for that type the stored value is the target being dialled. A PROVIDER_LOGIN in api_key mode uses its provider’s API-key probe; an Anthropic subscription setup-token retains its OAuth probe. An OpenAI PROVIDER_LOGIN in subscription mode does not: Crewship stores the OAuth access token extracted from a Codex auth.json and reconstructs the login file for the CLI; sending that token as an OpenAI API key tests the wrong credential. Older OpenAI AI_CLI_TOKEN auth blobs are likewise unprobeable. These return supported: false, valid: true under the existing unchecked-result convention, and an explanation in error. This is not proof that the login works; use a controlled agent run. Every other unprobeable provider likewise answers valid: true with supported: false — nothing failed because nothing was attempted. OPENAI_COMPAT and ENDPOINT_URL are actually dialled only here. Their endpoint is operator-supplied, so the dial is withheld on POST /api/v1/credentials/test above — that route is authenticated but carries no workspace or role floor, and dialling a caller-supplied host from it would make the server a blind-SSRF and internal-port-scan oracle. It answers “the endpoint URL is well-formed” and stops. This route is gated on canRole(role, "update") plus workspace visibility, and the URL was already vetted when the credential was created, so the reachability dial happens: the dialer resolves DNS first and refuses link-local and metadata addresses on the concrete IP, redirects are never followed so a 3xx cannot walk the probe onto a host the guard refused, and the probe offers no credential at all — not the stored key, not the custom headers. It asks for a model list, because reachability is the thing an operator cannot otherwise find out, and authentication is not worth turning the Test button into a way to post the stored secret at a baseURL that anyone holding “update” can repoint. Read supported before valid: supported: false means the credential was not checked, which is neither a pass nor a failure. valid retains its original meaning for existing clients.

Status	Condition
`403`	Insufficient role
`404`	Credential not found

POST /api/v1/credentials/{credentialId}/refresh

Forces a provider login’s access token to be renewed now from the sealed refresh token the server keeps (docs/prd/provider-logins.md §10.4). Only a PROVIDER_LOGIN in subscription mode with a stored refresh_token part — a ChatGPT login — can be refreshed. On success the new access, refresh and id tokens and the expiry are stored, a REFRESH audit event is recorded, and the file is re-rendered into the running containers of every Codex agent the login pays for. On a provider failure the login’s refresh state carries the error and the backoff; after three consecutive failures, or one the provider calls permanent (invalid_grant), refresh.status is needs_relogin and current workspace administrators get an inbox message, even if the original creator has since been demoted. The server also refreshes on its own: 24 h before expiry from the credential monitor, and before a run start with less than 48 h left. Auth: OWNER, ADMIN, or MANAGER role (canRole(role, "update")) plus workspace visibility. Request: No body. Response: 200 OK with { "login": { … } } — the login object after the refresh. 502 Bad Gateway with { "error", "login" } when the provider refused; the login’s refresh.status and refresh.error say why.

Status	Condition
`400`	The login has no refresh flow (a setup-token, an API key, a legacy row)
`403`	Insufficient role
`404`	Credential not found
`409`	Another refresh of this login is in flight (single-flight per login)
`503`	Refresh is not wired on this server

Rotation & Audit

Rotate secrets without downtime via an overlap grace window, inspect the append-only audit trail, and manage rotation history.

Audit Timeline

GET /api/v1/credentials/{credentialId}/audit?limit=50

Returns the credential’s append-only audit timeline (USE, ROTATE, TEST, REVOKE, DETECTED, CREATED events). Backs the Audit tab in the detail Sheet. (internal/api/credential_audit.go:276) Auth: OWNER, ADMIN, or MANAGER role (canRole(role, "update")). Audit reveals admin-action IPs, so VIEWER/MEMBER are blocked. Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	`50`	1-500. Out-of-range values fall back to the default.

Response: 200 OK — JSON array (newest first).

[
  {
    "id": "ca_01h9z7k0",
    "event_type": "ROTATE",
    "agent_id": null,
    "ip_address": "10.0.4.21",
    "metadata": { "rotation_id": "rot_abc", "grace_seconds": 86400, "rotated_by": "user_5" },
    "occurred_at": "2026-05-14T09:12:44Z"
  },
  {
    "id": "ca_01h9z6jp",
    "event_type": "USE",
    "agent_id": "agent_backend",
    "ip_address": "10.0.4.21",
    "metadata": null,
    "occurred_at": "2026-05-14T09:11:02Z"
  }
]

Status	Condition
`403`	Insufficient role
`404`	Credential not found (or in another workspace)

Rotate Credential

POST /api/v1/credentials/{credentialId}/rotate

Issues a new value and starts a configurable grace overlap window. The previous encrypted value is preserved on a new credential_rotations row for the grace window, then scrubbed when status transitions to EXPIRED or CANCELLED. (internal/api/credential_rotation.go:77) While the window is open, the previous value is consumed on a 401. A crew sidecar that boots inside the window receives it beside the new value (never in the agent’s environment), and when the provider answers 401 to the new value the sidecar replays the request exactly once with the previous one; the replay’s answer is what the agent sees, so a second 401 surfaces. Nothing else triggers it — a 403, a 429 or a 5xx is not retried, and only the rotated credential’s own previous value is used. The replay is recorded as a network.egress journal entry naming the credential and the rotation. A sidecar that was already running before the rotation is still on the previous value and needs no fallback.

Rotation replaces the live secret. The previous value is retained only for the grace window (then scrubbed), and the old value is scrubbed immediately when the rotation is expired or cancelled.

Auth: OWNER or ADMIN role, or any member holding the credential.rotate capability (layered gate requireRoleOrCapabilityOrForbid — lets an oncall MANAGER/MEMBER rotate a leaked token without blanket vault access) Request Body:

Field	Type	Required	Default	Description
`value`	string	Yes	—	New secret value (will be encrypted with AES-256-GCM). Max 64 KiB.
`grace_seconds`	integer	No	`86400`	Grace window in seconds. Range `0..604800` (7 days).

{
  "value": "sk-ant-api03-newvalue",
  "grace_seconds": 86400
}

Response: 200 OK

{
  "id": "rot_01h9z7k0abc",
  "credential_id": "cred_abc",
  "grace_seconds": 86400,
  "rotated_at": "2026-05-14T09:12:44Z",
  "expires_at": "2026-05-15T09:12:44Z",
  "rotated_by": "user_5",
  "status": "ACTIVE",
  "old_value_gone": false,
  "cancelled_at": null
}

The response is EXPIRED immediately when grace_seconds is 0; otherwise it starts as ACTIVE. cancelled_at is nullable and is set when a rotation is cancelled.

Status	Condition
`400`	Missing `value`, or `grace_seconds` outside `0..604800`
`401`	No authenticated user on the request
`403`	Insufficient role
`404`	Credential not found

List Rotations

GET /api/v1/credentials/{credentialId}/rotations

Returns the rotation history for a credential, newest first. Powers the Settings tab in the detail Sheet. (internal/api/credential_rotation.go:209) Auth: Session or CLI token + workspace membership. The same visibility filter as GET /credentials/{id} applies: MANAGER+ see every credential’s history; MEMBER/VIEWER only see WORKSPACE-scoped credentials or CREW-scoped ones belonging to a crew they are a member of. Response: 200 OK — JSON array. Each entry also includes nullable cancelled_at when a rotation was cancelled.

[
  {
    "id": "rot_01h9z7k0abc",
    "credential_id": "cred_abc",
    "grace_seconds": 86400,
    "rotated_at": "2026-05-14T09:12:44Z",
    "expires_at": "2026-05-15T09:12:44Z",
    "rotated_by": "user_5",
    "status": "ACTIVE",
    "old_value_gone": false
  }
]

old_value_gone is true once status is EXPIRED or CANCELLED (the old encrypted value has been scrubbed from the row).

Status	Condition
`404`	Credential not found
`404`	Credential exists but is not visible to the caller (same gate as `GET /credentials/{id}` — existence is not leaked)

Rotation Statuses

Status	Description
`ACTIVE`	Grace window open; a sidecar that booted inside it retries a `401` once with `old_value`
`EXPIRED`	Grace window elapsed; `old_value` scrubbed by the hourly expiry worker
`CANCELLED`	Operator ended grace early via `DELETE /credential-rotations/{rotationId}`; `old_value` scrubbed

Cancel Rotation (End Grace Early)

DELETE /api/v1/credential-rotations/{rotationId}

Ends an ACTIVE grace overlap immediately, scrubbing the stored old value. Idempotent: already-terminal rotations return 200 with the existing status. (internal/api/credential_rotation.go:258)

Cancelling a rotation scrubs the retained old value at once, ending sidecar 401-fallback before the grace window would otherwise elapse. A running sidecar drops its own copy after the next successful credential reconciliation (polled every 60 s). Reconciliation checks the exact rotation ID, so another active rotation cannot keep a cancelled value usable. If the metadata request fails, the boot-delivered expiry still bounds fallback locally.

Auth: OWNER or ADMIN role, or any member holding the credential.rotate capability (same layered gate as rotate — ending a grace window early is part of the rotation lifecycle) Response: 200 OK

{ "status": "CANCELLED" }

For an already-terminal rotation:

{ "status": "EXPIRED", "message": "rotation already terminal" }

Status	Condition
`403`	Insufficient role
`404`	Rotation not found, or its credential lives in another workspace

Bindings

A credential’s name is the account (github-acme). The slot is the environment variable the agent reads (GH_TOKEN). A binding connects them in one scope:

binding = (scope, slot) -> credential      scope: WORKSPACE | CREW | AGENT

Two rules govern the whole surface:

One slot, one credential, per scope. Enforced by a unique index; a conflicting write is refused with 409, never applied as a replacement.
Resolution is agent > crew > workspace. The most specific scope that binds a slot wins, and only that one is delivered.

A credential with no binding is delivered under its own name — the pre-binding behaviour, unchanged.

List Bindings

GET /api/v1/credentials/bindings

Query parameters (all optional, all exact-match): scope, crew_id, agent_id, credential_id, slot. Auth: Session or CLI token, workspace context required. Response: 200 OK

{
  "bindings": [
    {
      "id": "clx123",
      "credential_id": "clx456",
      "credential_name": "github-acme",
      "scope": "CREW",
      "crew_id": "clx789",
      "agent_id": null,
      "slot": "GH_TOKEN",
      "created_at": "2026-07-28T13:52:40Z"
    }
  ]
}

Create Binding

POST /api/v1/credentials/bindings

Role: OWNER / ADMIN (manage).

{
  "credential_id": "clx456",
  "scope": "CREW",
  "crew_id": "clx789",
  "slot": "GH_TOKEN"
}

Field	Required	Notes
`credential_id`	yes	Must belong to the caller’s workspace.
`scope`	no	`WORKSPACE` (default), `CREW` or `AGENT`.
`crew_id`	with `CREW`	Rejected for the other scopes.
`agent_id`	with `AGENT`	Rejected for the other scopes.
`slot`	yes	Environment variable name: `[A-Za-z_][A-Za-z0-9_]*`.

Response: 201 Created with the binding.

Status	When
`400`	Unknown scope, scope/owner mismatch, malformed slot, or a credential/crew/agent that does not exist in this workspace (indistinguishable from not-found on purpose — the response must not confirm another tenant’s ids).
`403`	Caller lacks the manage role.
`409`	The slot is already bound in that scope. The existing binding is left untouched.

Delete Binding

DELETE /api/v1/credentials/bindings/{bindingId}

Role: OWNER / ADMIN (manage). Response: 204 No Content, or 404 if the binding is not in the caller’s workspace. The row is really deleted — it is the slot claim, so anything that merely hid it would keep the slot occupied and 409 every later write. Bindings also cascade with their scope: deleting a crew, an agent, or the credential itself removes the bindings that pointed at it.

Resolve Slots for an Agent

GET /api/v1/agents/{agentId}/credential-bindings

Reports the slot map the agent will actually boot with, after resolution. Read-only, and values are never included. Response: 200 OK

{
  "agent_id": "clx001",
  "slots": [
    { "slot": "GH_TOKEN",  "credential_id": "clx456", "credential_name": "github-acme", "source": "crew_binding" },
    { "slot": "NPM_TOKEN", "credential_id": "clx999", "credential_name": "npm-publish", "source": "workspace_binding" }
  ]
}

source, most specific first: agent_grant (an explicit per-agent assignment), agent_binding, crew_binding, workspace_binding, crew_link (no binding — delivered under the credential’s own name). The response may also contain a warnings array when a credential was renamed, normalised, or could not be assigned a deliverable slot; warnings never contain secret values.

Custom Fields

Custom fields extend a credential with named parts such as a non-secret region or an additional secret. Field keys are lower snake case, start with a letter, and are limited to 64 characters. Secret field values are encrypted and are never returned; non-secret values are returned as value.

List Custom Fields

GET /api/v1/credentials/{credentialId}/fields

Auth: authenticated workspace member with visibility of the credential. Response: 200 OK

[
  { "key": "region", "is_secret": false, "ordinal": 0, "value": "us-east-1", "created_at": "2026-07-28T13:52:40Z", "updated_at": "2026-07-28T13:52:40Z" },
  { "key": "account_id", "is_secret": true, "ordinal": 1, "value": null, "created_at": "2026-07-28T13:52:40Z", "updated_at": "2026-07-28T13:52:40Z" }
]

Add Custom Field

POST /api/v1/credentials/{credentialId}/fields

Auth: MANAGER+ role.

{ "key": "region", "value": "us-east-1", "is_secret": false, "ordinal": 0 }

is_secret defaults to true when omitted. value is required and is capped at 64 KiB. The response is 201 Created with the field object. A missing or invisible credential returns 404; invalid keys/values or a duplicate key returns 400.

Update Custom Field

PUT /api/v1/credentials/{credentialId}/fields/{fieldKey} Auth: Authenticated workspace member with the create capability (the same write tier as updating the credential). Credential visibility is enforced against the current workspace; an invisible credential is reported as 404. Request: Path parameters are credentialId and fieldKey. JSON body:

{ "value": "eu-central-1", "is_secret": false, "ordinal": 0 }

value is required and capped at 64 KiB. is_secret and ordinal are optional; omitted is_secret preserves the field’s current classification, and the path key cannot be renamed. Response: 200 OK with the updated field object. Secret field values are omitted (value is null); non-secret values are returned. Statuses: 400 invalid JSON, key, value, or ordinal; 401 unauthenticated; 403 insufficient role/capability; 404 credential or field not found; 500 unexpected database or encryption failure.

Delete Custom Field

DELETE /api/v1/credentials/{credentialId}/fields/{fieldKey} Auth: Authenticated workspace member with the create capability. Credential visibility is enforced against the current workspace. Request: No body. credentialId and fieldKey are required path parameters. Response: 200 OK with { "success": true }. Statuses: 401 unauthenticated; 403 insufficient role/capability; 404 credential or field not found; 500 unexpected database failure.

Lookups & Assignment

Helper lookups and the cross-reference to per-agent credential assignment.

Default Environment Variable

GET /api/v1/credentials/default-env-var?provider={provider}

Returns the default environment variable name for a given provider (e.g., GH_TOKEN for GITHUB), and whether that provider can be probed. Recognised providers: GITHUB → GH_TOKEN, GITLAB → GITLAB_TOKEN, VERCEL → VERCEL_TOKEN, AWS → AWS_ACCESS_KEY_ID, KUBERNETES → KUBECONFIG; any other provider returns an empty string. The optional type parameter affects testable only: a credential of type ENDPOINT_URL is probeable whatever its provider, because the stored value is itself the target being dialled. env_var is derived from provider alone. Auth: Session or CLI token (no workspace context needed) Response: 200 OK

{ "env_var": "GH_TOKEN", "testable": true }

testable lets a client decide whether to offer a “Test” action without keeping its own list of probeable providers — the dashboard’s Add Credential form reads it for exactly that. The same flag rides on each credential in List and Get responses, so a detail view needs no extra call.

Agent Credential Assignment

See the Agents page for credential assignment endpoints:

Endpoint	Method	Description
`GET /api/v1/agents/{agentId}/credentials`	GET	List assigned credentials
`POST /api/v1/agents/{agentId}/credentials`	POST	Assign credential to agent
`DELETE /api/v1/agents/{agentId}/credentials/{assignmentId}`	DELETE	Remove assignment

A subscription login for a model provider can be created without pasting a file: the server drives the provider’s device-code authorization, the person enters a short code in the provider’s browser page, and the resulting login is stored as a PROVIDER_LOGIN credential owned by the caller. The server — not the client — polls the provider, so a closed tab or a CLI timeout does not lose the sign-in, and a pending sign-in survives a server restart. Only OPENAI (ChatGPT plans, delivered to the Codex adapter as a rendered auth.json) is offered today. CLI: crewship credential login --provider OPENAI.

POST /api/v1/provider-logins/device?workspace_id={workspaceId}

Auth: workspace OWNER or ADMIN. Provider-account administration has this role floor even when a lower role has the credential.create capability. Request body:

Field	Type	Required	Default	Description
`provider`	string	Yes	—	`OPENAI`
`mode`	string	No	`subscription`	Only `subscription` is offered by device code; an API key goes through Create Credential

{ "provider": "OPENAI" }

Response: 201 Created

{
  "device_id": "cmtppl…",
  "user_code": "ABCD-EFGHJ",
  "verification_url": "https://auth.openai.com/codex/device",
  "expires_at": "2026-09-06T11:15:00Z",
  "interval_s": 5
}

Show user_code and verification_url to the person, then poll the status endpoint every interval_s seconds until status leaves pending. The code is valid for 15 minutes.

Status	Condition
`400`	Unknown provider, or a `mode` other than `subscription`
`403`	Caller is not a workspace `OWNER` or `ADMIN`
`429`	More than 5 sign-ins started by this user in 10 minutes (`Retry-After` is set)
`502`	The provider refused to start the flow (device-code sign-in not offered, or unreachable)

GET /api/v1/provider-logins/device/{deviceId}

Auth: required. Only the user who started the sign-in can read it; any other id answers 404. Response: 200 OK

{
  "status": "complete",
  "credential_id": "cmtpq0…",
  "user_code": "ABCD-EFGHJ",
  "verification_url": "https://auth.openai.com/codex/device",
  "expires_at": "2026-09-06T11:15:00Z"
}

`status`	Meaning
`pending`	Waiting for the person to enter the code
`complete`	The login was stored; `credential_id` names it
`expired`	The 15-minute window passed before the code was entered; `error` says so
`denied`	The provider refused the sign-in, the token exchange failed, or the credential could not be stored; `error` says which

The created credential is named "ChatGPT <plan> · <email>" from the token’s plan claim and the account’s email, carries the whole login as its value (the refresh token is sealed on the server and replaced by a placeholder in every delivered file), and is otherwise exactly the row Create Credential would have produced — including its CREATED audit event.

Provider pools (account groups)

A pool — “account group” in the Credentials page — is a named set of provider accounts of one provider and one billing mode, in priority order, so that when one seat is unavailable another can take its turn. The API and CLI call it a pool; the UI calls it an account group; they are the same object (internal/api/provider_pool.go, internal/providerpool). A pool is a definition only. Creating one does not bind it to any agent, grant its members to anyone, decrypt a token or contact a provider; runtime selection is not wired to it yet. Every pool route, reads included, requires OWNER or ADMIN; a scoped CLI token additionally needs credentials:write for create, update and delete (reads need no scope). Capabilities for ordinary secrets do not grant pool access. Secret values are never returned. The CLI is crewship credential pool … (reference). Revisions and ETag. Each pool carries a revision that starts at 1 and increases by one on every PUT. GET one pool returns it as a strong ETag ("2"); PUT and DELETE require it back as If-Match and answer 412 when the pool has moved on, 428 when the header is missing, and 400 when it is not one quoted integer (wildcards, weak tags and lists are refused).

A pool member must be a credential of this workspace, and members must all carry the pool’s provider and mode: PROVIDER_LOGIN rows, or legacy API_KEY rows (read as api_key). Unknown and foreign-tenant ids fail the same way (400), so the existence of a credential in another tenant is not disclosed. Accounts owned by different people can only be pooled with allow_cross_owner: true; a member with no recorded owner cannot be pooled at all.

List provider pools

GET /api/v1/provider-logins/pools?workspace_id={workspaceId}

Auth: OWNER or ADMIN. Query Parameters:

Parameter	Type	Default	Description
`after`	string	—	Keyset cursor: the `next_cursor` of the previous page (a pool id; pools are ordered by id).

Response: 200 OK — up to 100 pools without their member lists.

{
  "items": [
    {
      "revision": 2,
      "id": "pool_abc",
      "name": "Team OpenAI",
      "provider": "OPENAI",
      "mode": "subscription",
      "allow_cross_owner": false,
      "created_by": "user_jdoe42",
      "member_count": 3
    }
  ],
  "next_cursor": null
}

next_cursor is null on the last page. Retired pools are not listed.

Create provider pool

POST /api/v1/provider-logins/pools?workspace_id={workspaceId}

Auth: OWNER or ADMIN. Request Body: unknown properties are rejected (400); the body limit is 64 KiB.

Field	Type	Required	Description
`name`	string	Yes	1–200 characters, unique within the workspace (retired names stay reserved).
`provider`	string	Yes	A model provider (`ANTHROPIC`, `OPENAI`, `GOOGLE`, …); folded onto its canonical spelling.
`mode`	string	Yes	`subscription` or `api_key`. Every member must carry it.
`allow_cross_owner`	boolean	No	Explicit consent to pool accounts owned by different people. Default `false`.
`members`	array	Yes	1–100 unique `{ "credential_id", "priority" }` entries. Lower `priority` is tried first; omitted is `0`.

{
  "name": "Team OpenAI",
  "provider": "OPENAI",
  "mode": "subscription",
  "allow_cross_owner": false,
  "members": [
    { "credential_id": "cred_seat1", "priority": 0 },
    { "credential_id": "cred_seat2", "priority": 10 }
  ]
}

Response: 201 Created with ETag: "1" — the pool as Get returns it, revision 1, members echoed.

Status	Condition
`400`	Invalid JSON, unknown property, bad name/provider/mode, no or too many members, a duplicate/unknown/foreign member, a member of another provider or mode, or `Pooling accounts from different owners requires explicit consent`
`403`	Below OWNER/ADMIN
`409`	`A provider pool with this name already exists`

An unavailable member (a seat waiting on re-login) does not fail creation; a malformed or mixed-owner set does. The create is audited (provider_pool.create) with the member count and consent flag only.

Get provider pool

GET /api/v1/provider-logins/pools/{poolId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN. Response: 200 OK with ETag: "<revision>" — the definition read in one snapshot, including members whose seat is revoked or expired, so an administrator can diagnose the set. It is not an availability probe.

{
  "revision": 2,
  "id": "pool_abc",
  "name": "Team OpenAI",
  "provider": "OPENAI",
  "mode": "subscription",
  "allow_cross_owner": false,
  "created_by": "user_jdoe42",
  "member_count": 2,
  "members": [
    { "credential_id": "cred_seat1", "priority": 0 },
    { "credential_id": "cred_seat2", "priority": 10 }
  ]
}

Field	Type	Description
`revision`	integer	Current revision; the same number the `ETag` header carries
`id`	string	Pool id
`name`	string	Display name
`provider`	string	Canonical provider
`mode`	string	`subscription` or `api_key`
`allow_cross_owner`	boolean	Whether mixed-owner membership was consented to
`created_by`	string?	User id of the creator
`member_count`	integer	Number of members
`members`	array	`{ "credential_id", "priority" }`, ordered by priority then id; omitted on list

Status	Condition
`403`	Below OWNER/ADMIN
`404`	No such pool in this workspace, or retired

Update provider pool

PUT /api/v1/provider-logins/pools/{poolId} Authentication: workspace OWNER/ADMIN; scoped CLI tokens also require credentials:write. Ordinary-secret capabilities do not grant pool access. Request headers: If-Match: "1" using the current ETag from Get. Wildcards, weak tags and tag lists are not accepted. Request body: complete replacement definition, not a patch:

{"name":"Team OpenAI","allow_cross_owner":false,"members":[{"credential_id":"account-id","priority":10}]}

Name is 1–200 characters; membership is 1–100 unique same-workspace IDs. Provider and authentication mode cannot change. Unknown properties are rejected, the body limit is 64 KiB, and cross-owner consent must be explicitly resubmitted. Response: 204, no body, with the new ETag. Retained members keep selection history; this does not assign credentials or enable runtime failover. Status codes: 400 invalid input, 401 unauthenticated, 403 forbidden, 404 missing/foreign/retired pool, 409 name conflict, 412 stale revision, 428 missing If-Match, 500 internal failure. Errors use {"error":"…"}. Inspect the new definition before retrying 412. Audit uses the existing best-effort settings audit; it is not transactionally coupled to the definition update.

Delete provider pool

DELETE /api/v1/provider-logins/pools/{poolId} Authentication: workspace OWNER/ADMIN, with credentials:write for scoped CLI tokens. Request headers: current If-Match: "2"; no request body. Response: 204, no body. Soft deletion hides the pool from list/detail and rejects future selection. Provider accounts and membership history remain; the name stays reserved. No upstream account is revoked. Status codes: 400 invalid revision, 401 unauthenticated, 403 forbidden, 404 missing/foreign/already-retired pool, 412 stale revision, 428 missing If-Match, 500 internal failure. Errors use {"error":"…"}. Retirement is audited through the same best-effort administrative audit. This increment manages definitions only; runtime bindings and active-execution protection are not enabled yet.

Reference

Enums and value sets used across the credential endpoints above.

Credential Types

The closed type enum (internal/api/credentials_types.go, enforced by both Create and Update):

Type	Description
`AI_CLI_TOKEN`	LLM API key (or OAuth bearer) for agent CLI adapters
`API_KEY`	External service API key
`CLI_TOKEN`	Generic CLI tool token
`SECRET`	Arbitrary secret value
`OAUTH2`	OAuth 2.0 token (managed via OAuth flow)
`USERPASS`	Username + password pair (`username` cleartext, password encrypted; requires `username`)
`SSH_KEY`	PEM-encoded private key (validated to begin with `-----BEGIN ... PRIVATE KEY-----`)
`CERTIFICATE`	PEM-encoded certificate (validated to begin with `-----BEGIN CERTIFICATE-----`)
`GENERIC_SECRET`	Opaque value, no shape validation
`PROVIDER_LOGIN`	A seat that pays for a model (`provider` ∈ `ANTHROPIC`, `OPENAI`, `GOOGLE`, `CURSOR`, `FACTORY`, `XAI`, `GROQ`, `OPENROUTER`, `DEEPSEEK`, `MOONSHOT`, `ZAI`, `MINIMAX`, `OPENCODE`, `OPENCODE_GO`, `ZAI_CODING_PLAN`; `mode` ∈ `subscription`, `api_key`). `value` is what the operator pasted — a setup-token, a whole Codex `auth.json`, or a key — and the server splits it into the value and the `refresh_token` / `id_token` / `account_id` / `plan` / `expires_at` / `mode` parts; a row with a refresh token is `SEALED`. Carries the `login` object.

Providers

provider is a free-form string. The values below are the ones with a live validation probe in the Test / Test Stored endpoints (internal/api/credentials_test_endpoint.go); any other provider value (including NONE) is accepted and stored, but Test returns valid: true with "No validation available for this provider".

Provider	Validation probe
`ANTHROPIC`	`GET api.anthropic.com/v1/models` (AI_CLI_TOKEN / `sk-ant-oat` tokens accepted without probing)
`OPENAI`	`GET api.openai.com/v1/models`
`GOOGLE`	`GET generativelanguage.googleapis.com/v1/models`
`CURSOR`	`GET api2.cursor.sh/v0/me`
`FACTORY`	`GET app.factory.ai/api/cli/auth/whoami`
`GITHUB`	`GET api.github.com/user`
`GITLAB`	`GET gitlab.com/api/v4/user`
`VERCEL`	`GET api.vercel.com/v2/user`
`OPENROUTER`	`GET openrouter.ai` key-metadata endpoint — the cheapest call that authenticates (no model list, no credits spent)
`OPENAI_COMPAT`	`GET {baseURL}/models`, falling back to `{baseURL}/api/tags` for an Ollama-native endpoint. Test Stored only — the body Test syntax-checks the URL without dialling, because the endpoint is operator-supplied. Reachability only: the stored `apiKey` and custom headers are never sent.
`NONE` / other	No probe (Generic / custom)

Statuses

Status	Description
`ACTIVE`	Ready to use
`PENDING`	Awaiting OAuth completion, or a manifest placeholder (`pending: true`)
`PENDING_APPROVAL`	An agent proposed a value through a `CREDENTIAL` escalation; a human approves or rejects it via `/resolve`
`REQUESTED`	An agent asked for a value it does not have; the row holds a sentinel until a human answers with `/supply`, after which it is `ACTIVE` and handle-only
`RATE_LIMITED`	Temporarily rate-limited
`EXPIRED`	Needs renewal
`REVOKED`	Manually revoked
`ERROR`	Validation/connection test failed

Revoking an LLM/provider token stops proxy injection within ~60s. A revoked credential is filtered out of every fresh delivery path immediately, and each agent’s sidecar also holds an in-memory snapshot of its provider tokens (loaded at container start). The sidecar reconciles that snapshot against the live set on a ~60s interval and drops any credential the server no longer lists (revoked or deleted), so a revoked provider key stops being injected into new outbound LLM requests within one interval — without waiting for the container to restart.File-based secrets are removed on revoke, too. File-based secrets written to /secrets/{agent-slug}/ (DB passwords, GH_TOKEN, SSH keys, certs) are materialized on disk at container start. On revoke (deleting a credential), the server reaches into every running crew container that mounted the credential as a file and removes the secret file(s) — exec’d inside the container as the agent UID (1001), the only principal that can unlink inside the agent’s 0700 secrets directory (the sidecar, UID 1002, cannot). This runs synchronously with the delete, so a successful revoke has already removed the files from live containers.

Removal is best-effort: a container that isn’t running is skipped (nothing to remove, and the revoked credential won’t be re-materialized on the next boot since it’s filtered from every delivery path). The .env hint-map keeps a now-inert reference to the removed file until the next container boot — harmless, since the file it points at is gone. If an exec fails transiently, recreate the crew container to force a clean rewrite.

Reveal

Reveal is the only endpoint in Crewship that returns a stored secret in plaintext. Every other read path omits values entirely.

Rotate instead, almost always. Most reasons to reveal a secret are really reasons to put a new secret somewhere. POST /credentials/{id}/rotate issues a new value, shows it once, and lets the old one drain through a grace window — no credential that is currently in use is ever exposed. Reveal exists for the cases where you genuinely need the value that is already deployed.

A reveal succeeds only when all of the following hold. Each is checked independently and each fails closed, so breaking one does not get you past the others.

Layer	Condition	Failure
Auth path	The caller presented an interactive sign-in session	`403`
Workspace switch	An OWNER has enabled reveal for the workspace	`403`
Role floor	Caller is MANAGER or above	`403`
Capability	Membership carries `credentials:reveal`	`403`
Tenancy	The credential belongs to the caller’s workspace	`404`
Crew scope	MANAGER: the credential is in one of their crews (OWNER/ADMIN exempt)	`403`
Classification	The credential is not `SEALED`	`403`
Reason	At least 20 characters and not a generic placeholder	`400`
Fresh sign-in	The session was created within the last 5 minutes — refreshing the page or the JWT does not renew it	`403` (`fresh_sign_in_required`)
Own password	The account is not still on the seed default password	`403` (`default_password`)
Chained audit	The tamper-evident audit entry committed	`500`

Agents, API tokens and CI can never reveal

The endpoint requires an interactive, revocable user session. A CLI token (crewship_cli_… / crewship_admin_…), an X-Internal-Token, a sidecar request, and any future auth method that does not explicitly opt in are all refused with 403. This is a gate on the credential shape, not on identity. An agent’s request carries a real user’s id and role — that is how delegation works — so “who is this?” cannot separate a person from a container. “What did they present?” can. An agent that needs a secret gets it through the normal delivery paths (env var, /secrets mount) or asks a human via Keeper escalation; it never reads one back out of the vault. Because of this, crewship credential reveal asks for your password and signs you in interactively rather than using the stored CLI token.

Capability, not role

credentials:reveal is granted per person on the membership and is what the gate checks; the role floor only says who may hold it. Since #2462 the admin preset includes it, and an OWNER or ADMIN whose membership has no explicit capability set holds it by default (BundleAdmin in internal/api/capabilities.go, the role fallback in capabilities_check.go). An explicit set is always authoritative: revoking credentials:reveal from an ADMIN removes it, and a MANAGER holds it only when granted. See Member capabilities. Recommended for corporate deployments: revoke it from the admin team and grant it to two people. The value is disclosed only to a session created in the last 5 minutes (internal/api/credentials_reveal_freshness.go). The clock is the server-side session creation time, not the JWT refresh or last activity, so a stolen session that is kept alive does not earn a reveal window; the CLI satisfies this by signing you in for the call. An account still on the seed default password is refused as well (default_password) — change it in account settings and sign in again.

Reveal Credential

POST /api/v1/credentials/{credentialId}/reveal

Auth: Interactive session only + workspace membership. CLI tokens, internal tokens and sidecars are refused. Rate limit: Dedicated per-IP bucket (http.cred_reveal_per_min, default 3/min) — far tighter than the general API bucket, and unlike it, authenticated CLI callers are not exempt. Request Body:

Field	Type	Required	Description
`reason`	string	yes	Why you need the value. Minimum 20 characters; generic placeholders (`test`, `debug`, `n/a`, a single word repeated) are rejected. Recorded verbatim in the audit chain.

{ "reason": "Migrating the deploy key into Vault, ticket OPS-812" }

Response: 200 OK with Cache-Control: no-store

{
  "credential_id": "cred_abc",
  "name": "GH_TOKEN",
  "type": "SECRET",
  "sensitivity": "STANDARD",
  "value": "ghp_…",
  "revealed_at": "2026-07-28T13:04:11Z",
  "journal_entry_id": "jrn_xyz"
}

journal_entry_id anchors the disclosure to the tamper-evident audit chain — quote it in an incident report and it can be verified. Errors:

Status	When
`400`	Reason missing, shorter than 20 characters, or generic
`403`	Any gate above refused; the message names which one (a stale sign-in says to sign out and in again; a default password says to change it first)
`404`	No such credential in this workspace (never `403` — the existence of an id in another tenant is not disclosed)
`429`	Reveal bucket exhausted
`500`	The chained audit entry could not be written — the value is not returned

The audit write is a precondition

The reveal is recorded in internal/journal, which is an HMAC hash-chain with signed compaction checkpoints, before the value is read out of the row. If that write fails, the request returns 500 and no value is returned. There is no “return it now, audit later” path. The flat credential_audit timeline also gets a REVEAL row so the disclosure appears in the credential’s detail Sheet next to every other event on it. That table has no hash chain — a row can be deleted without trace — which is exactly why it is not the authoritative record. What the journal payload contains: actor, credential id and name, classification, reason, actor role, client IP. What it never contains: the value, or any hash or fingerprint of it. A digest looks like a harmless identifier and is not — journal rows are readable by anyone with journal access and travel in every backup, and a digest of a short secret is crackable offline in seconds. Recording one would turn the audit log into a second copy of the vault.

Classification

Every credential carries a sensitivity. It is the first thing the reveal gate consults and the only one that no role can override.

Class	Reveal	Typical contents
`STANDARD`	With the full ceremony	Dev tokens, read-only keys
`RESTRICTED`	With the full ceremony	Production API keys, deploy keys
`SEALED`	Never, by any role, including OWNER	Production databases, root credentials, anything an agent created

SEALED has no escape hatch by design. Break-glass for a sealed credential is rotation: mint a new value, let the old one drain through its grace window. An escape hatch that exists is an escape hatch that gets used. Existing credentials default to STANDARD, which is safe only because the workspace reveal switch defaults to off.

RESTRICTED behaves identically to STANDARD today. The four-eyes second-approver flow that will distinguish them is deferred; classifying now still pays off, because that gate will key off this field.

Set Classification

PUT /api/v1/credentials/{credentialId}/sensitivity

Auth: Session or CLI token + workspace membership. Raising requires MANAGER+; lowering requires OWNER or ADMIN. The asymmetry is deliberate. Raising only ever removes reach, so it needs no ceremony — and if tightening is annoying, people stop tightening. Lowering hands out a key that did not exist a moment earlier, so it is written to the audit chain first and fails closed if that write fails. Request Body:

{ "sensitivity": "SEALED" }

Response: 200 OK

{ "credential_id": "cred_abc", "sensitivity": "SEALED", "previous": "STANDARD" }

A no-op change (same value) returns 200 and is not journaled. Errors: 400 unknown class · 403 lowering without OWNER/ADMIN · 404 not in this workspace · 500 audit write failed (the classification is unchanged)

Workspace Reveal Policy

Reveal is off for every workspace until an OWNER turns it on, including freshly created ones. A default of “on” would make a new tenant’s security posture depend on someone remembering to lock it.

Read Reveal Policy

GET /api/v1/credentials/reveal-policy

Auth: Session or CLI token + MANAGER or above. MEMBER and VIEWER get 403 — whether a tenant has reveal enabled is target-selection information. A MANAGER reads it because they need to know the rules they work under, but cannot change it. Response: 200 OK

{ "workspace_id": "ws_abc", "enabled": false }

Set Reveal Policy

PUT /api/v1/credentials/reveal-policy

Auth: Session or CLI token + OWNER only. Journaled as a precondition: if the chained write fails, the switch does not move. An attacker who can wedge the audit log must not be able to open a tenant’s reveal surface unobserved. Both directions are recorded. Request Body:

{ "enabled": true }

Response: 200 OK

{ "workspace_id": "ws_abc", "enabled": true }

Enabling the switch does not grant anyone reveal on its own — each person still needs credentials:reveal on their membership. Errors: 400 body is not {"enabled": bool} · 403 caller is not OWNER · 500 audit write failed (switch unchanged)

​Endpoints

​Credential endpoints

​Endpoint contract

​Managing Credentials

​Explain your credential access

​Routine dependents

​List Credentials

​Response Fields

​Create Credential

​Get Credential

​Update Credential

​Delete Credential

​Validating Credentials

​Test Credential

​Test Stored Credential

​Refresh Provider Login

​Rotation & Audit

​Audit Timeline

​Rotate Credential

​List Rotations

​Rotation Statuses

​Cancel Rotation (End Grace Early)

​Bindings

​List Bindings

​Create Binding

​Delete Binding

​Resolve Slots for an Agent

​Custom Fields

​List Custom Fields

​Add Custom Field

​Update Custom Field

​Delete Custom Field

​Lookups & Assignment

​Default Environment Variable

​Agent Credential Assignment

​Provider logins — sign in with a device code

​Start a device-code sign-in

​Device-code sign-in status

​Provider pools (account groups)

​List provider pools

​Create provider pool

​Get provider pool

​Update provider pool

​Delete provider pool

​Reference

​Credential Types

​Providers

​Statuses

​Reveal

​Agents, API tokens and CI can never reveal

​Capability, not role

​A fresh sign-in, on your own password

​Reveal Credential

​The audit write is a precondition

​Classification

​Set Classification

​Workspace Reveal Policy

​Read Reveal Policy

​Set Reveal Policy

Endpoints

Credential endpoints

Endpoint contract

Managing Credentials

Explain your credential access

Routine dependents

List Credentials

Response Fields

Create Credential

Get Credential

Update Credential

Delete Credential

Validating Credentials

Test Credential

Test Stored Credential

Refresh Provider Login

Rotation & Audit

Audit Timeline

Rotate Credential

List Rotations

Rotation Statuses

Cancel Rotation (End Grace Early)

Bindings

List Bindings

Create Binding

Delete Binding

Resolve Slots for an Agent

Custom Fields

List Custom Fields

Add Custom Field

Update Custom Field

Delete Custom Field

Lookups & Assignment

Default Environment Variable

Agent Credential Assignment

Provider logins — sign in with a device code

Start a device-code sign-in

Device-code sign-in status

Provider pools (account groups)

List provider pools

Create provider pool

Get provider pool

Update provider pool

Delete provider pool

Reference

Credential Types

Providers

Statuses

Reveal

Agents, API tokens and CI can never reveal

Capability, not role

A fresh sign-in, on your own password

Reveal Credential

The audit write is a precondition

Classification

Set Classification

Workspace Reveal Policy

Read Reveal Policy

Set Reveal Policy