> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Rotate and list API keys for the current tenant.

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

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

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

```http theme={null}
POST /v1/credentials/rotate
```

```bash theme={null}
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**

```json theme={null}
{
  "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

```http theme={null}
GET /v1/credentials?user_id={id}
```

Returns metadata only — never the plaintext secret.

```json theme={null}
{
  "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` |