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

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
`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
`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

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

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 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`.

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
`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
`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. 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)
`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:319) 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.
`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-3)

Note: The status field cannot be updated via this endpoint. Status changes are managed by the credential monitor and OAuth refresh worker.

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
`403`	Insufficient role
`404`	Credential not found

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 }.

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, "supported": bool }. supported reports whether a real upstream probe ran. Crewship maintains probes for ANTHROPIC, OPENAI, GOOGLE, CURSOR, FACTORY, GITHUB, GITLAB and VERCEL, plus any credential of type ENDPOINT_URL. Every other provider falls through to a no-op that answers valid: true — literally true, since nothing failed, but nothing was attempted either. 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

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 sidecar 401-fallback during the grace window, then scrubbed when status transitions to EXPIRED or CANCELLED. (internal/api/credential_rotation.go:77)

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; sidecar may fall back to `old_value` on 401
`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.

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

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

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
`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`
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. It is deliberately absent from every capability bundle, including the admin bundle, so an OWNER or ADMIN whose membership has never been touched does not hold it. Being an OWNER is necessary for workspace-wide reveal and never sufficient. Recommended for corporate deployments: two people hold it, not the whole admin team.

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
`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)

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

Providers

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
`RATE_LIMITED`	Temporarily rate-limited
`EXPIRED`	Needs renewal
`REVOKED`	Manually revoked
`ERROR`	Validation/connection test failed

​Endpoints

​Endpoint contract

​Managing Credentials

​List Credentials

​Response Fields

​Create Credential

​Get Credential

​Update Credential

​Delete Credential

​Validating Credentials

​Test Credential

​Test Stored Credential

​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

​Reference

​Credential Types

​Providers

​Statuses

​Reveal

​Agents, API tokens and CI can never reveal

​Capability, not role

​Reveal Credential

​The audit write is a precondition

​Classification

​Set Classification

​Workspace Reveal Policy

​Read Reveal Policy

​Set Reveal Policy

​Reference

​Credential Types

​Providers

​Statuses

Endpoints

Endpoint contract

Managing Credentials

List Credentials

Response Fields

Create Credential

Get Credential

Update Credential

Delete Credential

Validating Credentials

Test Credential

Test Stored Credential

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

Reference

Credential Types

Providers

Statuses

Reveal

Agents, API tokens and CI can never reveal

Capability, not role

Reveal Credential

The audit write is a precondition

Classification

Set Classification

Workspace Reveal Policy

Read Reveal Policy

Set Reveal Policy

Reference

Credential Types

Providers

Statuses