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

# API Keys: Create, Rotate, Revoke, and Delete Keys

> Manage programmatic API keys in Scrubbe — create scoped keys for environments, rotate credentials on a schedule, and revoke or delete keys you no longer need.

API keys let server-side applications and ingestion pipelines authenticate with Scrubbe without user credentials. Each key is scoped to specific permissions and an environment, so you can apply the principle of least privilege to every integration. All endpoints in this section require `Authorization: Bearer <accessToken>` and live under `/api/v1/apikey`.

<Warning>
  An API key's secret value is shown **only once** immediately after creation. Store it in a secrets manager immediately — it cannot be retrieved again. If lost, rotate or delete the key and create a new one.
</Warning>

***

## POST /apikey/createapikey

Create a new API key scoped to a specific environment and set of permissions.

<ParamField body="name" type="string" required>
  A human-readable label for the key. Example: `"Production Key"`.
</ParamField>

<ParamField body="environment" type="string" required>
  Target environment. One of: `PRODUCTION`, `STAGING`, `DEVELOPMENT`.
</ParamField>

<ParamField body="scopes" type="string[]" required>
  Array of permission scopes granted to this key. Example: `["incidents:read", "incidents:write"]`.
</ParamField>

<ParamField body="expiresAt" type="string">
  ISO 8601 expiry timestamp. Omit for a non-expiring key. Example: `"2026-12-31T00:00:00Z"`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://your-api-domain.com/api/v1/apikey/createapikey" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --data '{
      "name": "Production Key",
      "environment": "PRODUCTION",
      "scopes": ["incidents:read", "incidents:write"],
      "expiresAt": "2026-12-31T00:00:00Z"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://your-api-domain.com/api/v1/apikey/createapikey', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      name: 'Production Key',
      environment: 'PRODUCTION',
      scopes: ['incidents:read', 'incidents:write'],
      expiresAt: '2026-12-31T00:00:00Z'
    })
  });
  const { data } = await response.json();
  // Save data.key — it will not be shown again
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://your-api-domain.com/api/v1/apikey/createapikey",
      headers={"Authorization": f"Bearer {access_token}"},
      json={
          "name": "Production Key",
          "environment": "PRODUCTION",
          "scopes": ["incidents:read", "incidents:write"],
          "expiresAt": "2026-12-31T00:00:00Z"
      }
  )
  key_secret = resp.json()["data"]["key"]  # store immediately
  ```
</CodeGroup>

**201 response**

```json theme={null}
{
  "success": true,
  "message": "API key created successfully.",
  "data": {
    "id": "apk_01HX...",
    "name": "Production Key",
    "key": "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "environment": "PRODUCTION",
    "scopes": ["incidents:read", "incidents:write"],
    "expiresAt": "2026-12-31T00:00:00Z",
    "createdAt": "2025-06-01T09:00:00Z"
  }
}
```

<ResponseField name="data.key" type="string">
  The full API key secret. Shown only once — store it securely before leaving this response.
</ResponseField>

<ResponseField name="data.id" type="string">
  The key ID used for rotate, revoke, and delete operations.
</ResponseField>

***

## GET /apikey/apikeys

List all API keys for the authenticated user's workspace. The key secret is **not** included in list responses.

```json theme={null}
{
  "success": true,
  "message": "API keys retrieved.",
  "data": [
    {
      "id": "apk_01HX...",
      "name": "Production Key",
      "environment": "PRODUCTION",
      "scopes": ["incidents:read", "incidents:write"],
      "expiresAt": "2026-12-31T00:00:00Z",
      "lastUsedAt": "2025-05-20T14:22:00Z",
      "createdAt": "2025-06-01T09:00:00Z"
    }
  ]
}
```

***

## POST /apikey/:id/rotate

Generate a new secret for an existing key. The old secret is immediately invalidated. The new secret is shown only in the rotation response.

<ParamField path="id" type="string" required>
  The ID of the key to rotate.
</ParamField>

```json theme={null}
{
  "success": true,
  "message": "API key rotated successfully.",
  "data": {
    "id": "apk_01HX...",
    "key": "sk_prod_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  }
}
```

<Tip>
  Automate key rotation on a regular schedule (e.g., every 90 days) to limit the blast radius of a compromised credential.
</Tip>

***

## POST /apikey/:id/revoke

Disable a key immediately without deleting it. The key record is retained for audit purposes but will no longer authenticate requests.

<ParamField path="id" type="string" required>
  The ID of the key to revoke.
</ParamField>

```json theme={null}
{
  "success": true,
  "message": "API key revoked successfully.",
  "data": {}
}
```

***

## DELETE /apikey/:id

Permanently delete a key and its audit record. This action cannot be undone.

<ParamField path="id" type="string" required>
  The ID of the key to delete.
</ParamField>

```json theme={null}
{
  "success": true,
  "message": "API key deleted.",
  "data": {}
}
```

<Warning>
  Deleting a key is irreversible. Prefer revoke if you want to retain the audit trail.
</Warning>

## Available scopes

| Scope                | Description                            |
| -------------------- | -------------------------------------- |
| `incidents:read`     | Read incident data                     |
| `incidents:write`    | Create and update incidents            |
| `postmortems:read`   | Read postmortem reports                |
| `postmortems:write`  | Create and update postmortems          |
| `analytics:read`     | Access dashboard metrics and analytics |
| `integrations:read`  | Read integration configuration         |
| `integrations:write` | Create and modify integrations         |
| `ingestion:write`    | Push events via ingestion endpoints    |