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

# API Keys

> Create, scope, monitor, rotate, suspend, revoke, and securely use CaseBender API keys.

## Overview

API keys provide programmatic access to CaseBender. Open **Settings → Account → API Keys** to manage keys available to your account and current organization.

The page provides:

* Search and status or tier filters
* Masked key identifiers
* Status, tier, last-used time, and request count
* Usage statistics
* Lifecycle actions such as rotation, suspension, revocation, and deletion

<Warning>
  An API key is a credential. Store it in an approved secrets manager, never commit it to source control, and never include it in logs, screenshots, tickets, or chat messages.
</Warning>

## Prerequisites

* Your role must allow write operations and API-key management.
* Available scopes are filtered according to your role.
* Creating, revoking, or deleting a key can require step-up authentication.
* Your organization can impose additional authentication and access policies.

Read-only roles can view permitted information but cannot mutate keys.

## Create an API key

<Steps>
  <Step title="Open API Keys">
    Go to **Settings → Account → API Keys**.
  </Step>

  <Step title="Start creation">
    Select **Create API Key**.
  </Step>

  <Step title="Describe the key">
    Enter a clear **Name** and optional description identifying the workload, owner, and purpose.
  </Step>

  <Step title="Select a tier">
    Choose the tier appropriate for the workload's expected request volume. Available tiers range from **Basic** through **Unlimited**.
  </Step>

  <Step title="Set an expiration">
    Optionally enter the number of days until expiration. Prefer short, policy-aligned lifetimes for production credentials.
  </Step>

  <Step title="Select scopes">
    Choose at least one scope. Use **Select all** only when the workload legitimately requires every scope available to your role.
  </Step>

  <Step title="Create and authenticate">
    Select **Create Key** and complete step-up authentication when prompted.
  </Step>

  <Step title="Save the credential">
    Copy the complete key from **Save Your API Key** into an approved secrets manager before selecting **Done**.
  </Step>
</Steps>

<Warning>
  The complete key is displayed only once. CaseBender stores only the information required to validate and identify it; the plaintext credential cannot be retrieved later.
</Warning>

## Choose scopes

Scopes use a resource-and-action pattern, such as `cases:read` or `organizations:*`. Scope categories can include cases, alerts, tasks, users, teams, organizations, settings, and API-key management.

Follow least privilege:

* Use read-only scopes for reporting and search workloads.
* Grant write scopes only when the integration performs mutations.
* Avoid wildcard and administrative scopes for single-purpose integrations.
* Create separate keys for unrelated services or environments.
* Review scope requirements whenever an integration changes.

The Settings creation form only offers scopes allowed by your current role. API requests are evaluated against the key's scopes and other enforced data controls.

<Warning>
  Grant `api-keys:write`, wildcard, or administrative scopes only to trusted automation that is explicitly authorized to create or manage other credentials.
</Warning>

## Choose a tier

The tier records the intended service class for a key. The available tiers are:

* **Basic**
* **Standard**
* **Professional**
* **Enterprise**
* **Unlimited**

Effective request, bulk-operation, and concurrency limits depend on deployment configuration. Validate production throughput and enforcement with your platform administrator rather than assuming that selecting a tier changes the active limits or makes a key unrestricted.

## Authenticate API requests

Use the complete key with one of the supported single-key headers.

### Recommended: Bearer token

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "Authorization: Bearer $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

### Alternative: X-Api-Key

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "X-Api-Key: $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

<Note>
  Store the key in an environment variable or secret injection mechanism. Do not paste a real key directly into shell history or source code.
</Note>

See the [API Reference introduction](/api-reference/introduction) for additional examples.

## Understand key statuses

* **Active** keys can authenticate requests, subject to scope and policy checks.
* **Suspended** keys are temporarily disabled and can be reactivated.
* **Revoked** keys are permanently invalid.
* **Expired** keys have passed their configured expiration.

## View usage statistics

Open a key's action menu and select **View Stats** to review:

* Total requests
* Successful requests
* Failed requests
* Average response time
* Top endpoints

Use these statistics to identify unused credentials, unexpected endpoints, and workloads that require a different tier.

## Rotate a key

Rotation replaces the current secret with a new one.

<Steps>
  <Step title="Prepare the consumer">
    Confirm that you can update the consuming service immediately and have a rollback plan.
  </Step>

  <Step title="Rotate">
    Open the key's action menu and select **Rotate Key**.
  </Step>

  <Step title="Save the new key">
    Copy the newly displayed credential into your secrets manager.
  </Step>

  <Step title="Update and verify">
    Update the consuming workload, restart or redeploy it as required, and make a scoped test request.
  </Step>
</Steps>

<Warning>
  Rotation invalidates the previous secret. Coordinate the change to avoid an integration outage.
</Warning>

Rotation is operator-initiated. A stored rotation interval does not by itself guarantee that CaseBender will rotate and distribute a replacement key automatically.

## Suspend or reactivate a key

Use **Suspend** to stop a key temporarily during an investigation or planned maintenance. Use **Reactivate** only after confirming that the credential and its consumer are trusted.

Suspension is preferable to deletion when you need a reversible containment action.

## Revoke a key

Use **Revoke** when a credential is compromised, no longer trusted, or permanently retired. Revocation can require step-up authentication and cannot be reversed.

After revocation:

1. Remove the secret from all consumers.
2. Review usage statistics and security telemetry.
3. Investigate unexpected requests.
4. Create a separate replacement key only if the workload remains authorized.

## Delete a key

Deletion removes the key record and its direct management visibility. It can require step-up authentication.

<Warning>
  Revoke a key before deleting it when you need a clear credential-retirement sequence. The current action menu does not provide a separate confirmation dialog for every destructive operation.
</Warning>

## Security recommendations

* Assign a named human owner and workload owner.
* Use separate keys for production, staging, and development.
* Set an expiration aligned with your credential policy.
* Rotate immediately after suspected exposure.
* Monitor failed requests and unexpected endpoints.
* Revoke unused keys instead of leaving them active.
* Never send keys through email or collaboration tools.

## Troubleshooting

### Create Key is rejected

Enter a name, select at least one scope, confirm that your role has write access, and complete any step-up authentication challenge.

### An API request returns 401

Confirm that the complete active key is supplied as a Bearer token or `X-Api-Key`, and verify that it has not expired, been suspended, or been revoked.

### An API request returns 403

The key authenticated successfully but lacks the required scope or data access. Add only the minimum required scope through an authorized key-management workflow.

### Requests are rate limited

Reduce request frequency, honor retry guidance from the response, or ask an administrator whether the workload requires another tier.

### The complete key is no longer visible

Plaintext keys cannot be retrieved. Rotate the key or create a replacement and update the consumer.

## API reference

* [List API keys](/api-reference/endpoint/api-keys/list)
* [Create an API key](/api-reference/endpoint/api-keys/create)
* [List available scopes](/api-reference/endpoint/api-keys/scopes)
* [Get an API key](/api-reference/endpoint/api-keys/get-by-id)
* [Rotate an API key](/api-reference/endpoint/api-keys/rotate)
* [View API key statistics](/api-reference/endpoint/api-keys/stats)
* [Delete an API key](/api-reference/endpoint/api-keys/delete)

## Related guides

* [API Reference introduction](/api-reference/introduction)
* [Access Control](/security/access-control)
* [Organizations](./organizations.mdx)