> ## 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, and Revoke Access Keys

> Create scoped API keys for production and staging, list active keys, rotate credentials on demand, and revoke or delete keys you no longer need.

API keys are the primary way to authenticate requests to the Scrubbe API from your own applications, scripts, or integrations. Each key is scoped to a specific environment and a set of permissions, so you can follow the principle of least privilege across your systems.

<Warning>Scrubbe shows the raw API key value **only once** — immediately after creation. Copy and store it securely before leaving the page or closing the response. If you lose the key, you must rotate or delete it and create a new one.</Warning>

## Create an API key

Send a `POST` request with a name, environment, permission scopes, and an optional expiry date.

```http theme={null}
POST /api/v1/apikey/createapikey
```

<CodeGroup>
  ```json Request body theme={null}
  {
    "name": "Production Key",
    "environment": "PRODUCTION",
    "scopes": ["incidents:read", "incidents:write"],
    "expiresAt": "2026-12-31T00:00:00Z"
  }
  ```

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

| Field         | Type   | Required | Description                                                                            |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | A human-readable label to identify the key in your dashboard.                          |
| `environment` | string | Yes      | One of `PRODUCTION`, `STAGING`, or `DEVELOPMENT`.                                      |
| `scopes`      | array  | Yes      | List of permission scopes granted to this key.                                         |
| `expiresAt`   | string | No       | ISO 8601 datetime after which the key is no longer valid. Omit for a non-expiring key. |

The response includes the raw key value in a field such as `key` or `rawKey`. **This value is not retrievable again after this response.** Store it in a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's secret store) before proceeding.

<Tip>Use a separate key per environment and per integration. This limits the blast radius if a key is ever compromised, and makes it easy to rotate or revoke access for a single service without affecting others.</Tip>

## Use an API key in requests

Pass the key in the `X-API-Key` header on every request that requires authentication.

```bash cURL theme={null}
curl --request GET \
  --url https://api.scrubbe.com/api/v1/incidents \
  --header 'X-API-Key: YOUR_API_KEY'
```

<Note>Do not include API keys in query parameters or request bodies. Always use the `X-API-Key` header to keep the key out of server access logs and browser history.</Note>

## List your API keys

Retrieve metadata for all API keys associated with your account. The raw key value is never returned in this response — only key IDs, names, environments, scopes, and status.

```http theme={null}
GET /api/v1/apikey/apikeys
```

```bash cURL theme={null}
curl --request GET \
  --url https://api.scrubbe.com/api/v1/apikey/apikeys \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

## Rotate a key

Rotating a key invalidates the current key value and issues a new one under the same key ID. Use rotation on a regular schedule or immediately if you suspect a key has been exposed.

```http theme={null}
POST /api/v1/apikey/:id/rotate
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.scrubbe.com/api/v1/apikey/KEY_ID/rotate \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

The response returns the new raw key value. As with key creation, this value is shown **only once**. Update your application configuration before the old key stops working.

<Warning>After rotation, any application still using the old key will start receiving authentication errors immediately. Make sure you update all consumers of the key before or immediately after rotating.</Warning>

## Revoke a key

Revoking a key disables it without deleting it. A revoked key cannot be used to authenticate requests, but its record remains visible in your key list.

```http theme={null}
POST /api/v1/apikey/:id/revoke
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.scrubbe.com/api/v1/apikey/KEY_ID/revoke \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

## Delete a key

Permanently removes the key and its metadata from your account. This action cannot be undone.

```http theme={null}
DELETE /api/v1/apikey/:id
```

```bash cURL theme={null}
curl --request DELETE \
  --url https://api.scrubbe.com/api/v1/apikey/KEY_ID \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

<Warning>Deleting a key is permanent. If an active integration is still using the deleted key, it will fail immediately. Prefer revoking a key if you may need to reference it later, and only delete when you are certain the key is no longer in use.</Warning>

## Key management summary

| Action | Endpoint                           | Effect                                  |
| ------ | ---------------------------------- | --------------------------------------- |
| Create | `POST /api/v1/apikey/createapikey` | Issues a new key; raw value shown once. |
| List   | `GET /api/v1/apikey/apikeys`       | Returns key metadata, never raw values. |
| Rotate | `POST /api/v1/apikey/:id/rotate`   | Invalidates old value, issues new one.  |
| Revoke | `POST /api/v1/apikey/:id/revoke`   | Disables key; record is preserved.      |
| Delete | `DELETE /api/v1/apikey/:id`        | Permanently removes key and record.     |