Credentials

API keys (credentials) authenticate service-to-service callers. Each credential is bound to a single user identity and inherits that user’s role assignments.

Credentials are non-extractable after creation. The plaintext value is returned only once in the rotation response. Store it in your secret manager immediately.

Rotate credential

Creates a new credential for the calling user (or for user_id if the caller is admin) and revokes any previous credential bound to the same user.

POST /v1/credentials/rotate

curl -X POST https://api.qustody.io/v1/credentials/rotate \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_01HXYZ...", "label": "ci-deploy-bot"}'

Response 201

{
  "id": "cred_01HXYZ...",
  "user_id": "usr_01HXYZ...",
  "label": "ci-deploy-bot",
  "secret": "qcs_live_abc...xyz",
  "created_at": "2026-04-27T10:15:00Z",
  "expires_at": null
}

After this response, send Authorization: Bearer qcs_live_abc...xyz on subsequent calls.

List credentials

GET /v1/credentials?user_id={id}

Returns metadata only — never the plaintext secret.

{
  "credentials": [
    {
      "id": "cred_01HXYZ...",
      "user_id": "usr_01HXYZ...",
      "label": "ci-deploy-bot",
      "last_used_at": "2026-04-27T10:30:00Z",
      "revoked_at": null,
      "created_at": "2026-04-27T10:15:00Z"
    }
  ]
}

Required permissions

Endpoint	Permission
`POST /v1/credentials/rotate`	`credentials:create` (or self-rotation)
`GET /v1/credentials`	`credentials:read`

Errors

Code	Type	When
1000	`UNAUTHORIZED`	Bearer missing or invalid
1002	`API_KEY_REVOKED`	Credential revoked
1101	`MISSING_FIELD`	`user_id` required when caller is `admin`

Users and roles Audit

Overview

Health

Tenants

Vaults

Wallets

Transactions

Assets

Tokens

Webhooks

Administration

Rotate credential

List credentials

Required permissions

Errors

​Rotate credential

​List credentials

​Required permissions

​Errors

Rotate credential

List credentials

Required permissions

Errors