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

# Create and manage API keys

> Choose scopes, store credentials, rotate keys, and diagnose authentication problems.

An API key belongs to an organization and is limited by both its selected scopes and its owner's role. Create separate keys for each application and environment.

<Steps>
  <Step title="Generate a key">
    Open **Integrations** → **API Keys** and choose **Generate API Key**. Give it a name identifying the application and environment, select the required scopes, and optionally set an expiration.
  </Step>

  <Step title="Store the secret">
    Copy the value when it is displayed and put it in your application's secret store or server environment. Key details show metadata, not a recoverable copy of the original secret.
  </Step>

  <Step title="Verify read access">
    With a key that has `templates:read`, request `GET /v1/templates` using the API URL for the same environment. See [Send with the API](/guides/send-with-api).
  </Step>
</Steps>

## Scope and role matrix

Each row adds to the permissions above it. Having a role does not automatically add every permitted scope to a key.

| Minimum role   | Scopes available                                                                                                                                                                          |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Viewer         | `templates:read`, `entities:read`, `sample-data:read`, `usage:read`, `organizations:read`, `queues:read`, `destinations:read`, `interactions:read`                                        |
| Member         | `templates:create`, `templates:update`, `templates:activate`, `entities:write`, `messages:create`, `messages:preview`, `scheduled:read`, `scheduled:write`, `modals:read`, `modals:write` |
| Admin or owner | `templates:delete`, `organizations:write`, `users:read`, `users:write`, `queues:write`, `destinations:write`                                                                              |

Compile and send both require `messages:create`. Reading templates does not permit sending. A typical sender uses `templates:read` to discover templates and inputs, plus `messages:create` to deliver. Grant `templates:activate` separately when an application should be allowed to select the version used by future sends.

## Rotate and revoke

For a planned rotation, generate a replacement key, update the application, verify a request, and revoke the old key from its action menu. **Recycle Key** replaces an existing credential; coordinate the application update before using it.

Revocation and scope changes can take up to 15 minutes to reach cached API authentication. If a credential is exposed, revoke it, remove it from the exposed location, and contact support if you need help containing ongoing access.

## Troubleshoot

| Response                        | Check                                                                |
| ------------------------------- | -------------------------------------------------------------------- |
| 401                             | Key spelling, Bearer header, expiration/revocation, and environment  |
| 403 with `required_scopes`      | Add the named scope using a role allowed to grant it                 |
| Resource not found              | Resource ID and key must belong to the same organization/environment |
| Missing scope in the key editor | Your role or the environment's feature availability                  |

Use the machine-readable `code` and `request_id` when reporting failures. Never include the key in a support message. See [Organization access](/guides/organization-access).