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

# Authentication

> Authenticate to the Chronicle API with a workspace-scoped API key.

API keys let your application create, generate, fetch, and update presentations on behalf of a Chronicle workspace.

When you create a key:

* It belongs to a specific workspace
* It can access resources in that workspace

***

## Create an API key

<Steps>
  <Step title="Open API Settings ">
    Go to Settings → API in the [Chronicle](https://app.chroniclehq.com) web app.
  </Step>

  <Step title="Create a key">
    Click Create API Key
  </Step>

  <Step title="Copy and store securely">
    Copy the key immediately, it will only be shown once.

    Store it in a secure location such as an environment variable or secrets manager.
  </Step>
</Steps>

## Use the API key

Include the key in the header with every request:

Supported headers:

* `Authorization: Bearer <API_KEY>`
* `x-api-key: <API_KEY>`

Use one method consistently across your integration.

### Using `Authorization`

```text theme={null}
curl -X GET "https://api.chroniclehq.com/api/v1/templates" \
  -H "Authorization: Bearer $CHRONICLE_API_KEY"
```

### Using `x-api-key`

```text theme={null}
curl -X GET "https://api.chroniclehq.com/api/v1/templates" \
  -H "x-api-key: $CHRONICLE_API_KEY"
```

***

## Store keys securely

* Use API keys only in server-side code
* Never expose keys in frontend applications
* Never commit keys to source control
* Rotate keys periodically
* Revoke keys that are no longer needed
* Use separate keys per environment when possible

<Warning>
  Keep your API keys secure and never share them publicly. Each key provides full access to your Chronicle workspace. If a key is compromised, revoke it immediately from the settings page.
</Warning>

***

## Authentication errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Returned when:

    * The key is missing
    * The key is invalid
    * The key is expired
    * The key is revoked
    * The auth header is malformed
  </Accordion>

  <Accordion title="403 Forbidden">
    Returned when the key is valid but the resource is outside the key's workspace. Each API key is bound to a single workspace and can only see resources in that workspace.
  </Accordion>
</AccordionGroup>

***

## FAQs

<AccordionGroup>
  <Accordion title="Do I use an API key or a user token?">
    Use an API key for the public REST API.

    Create the key in Chronicle, store it securely, and send it with requests to `/api/v1/...`.
  </Accordion>

  <Accordion title="How do I send my API key?">
    Send it as either:

    * `Authorization: Bearer <API_KEY>`
    * `x-api-key: <API_KEY>`

    Use one method consistently across your integration.
  </Accordion>

  <Accordion title="Why did I only see the raw key once?">
    For security reasons, Chronicle only shows the raw API key once.

    Copy it when you create it and store it in your secret manager. If you lose it, create a new key.
  </Accordion>

  <Accordion title="Why am I getting 403 even though my key is valid?">
    A `403` means your key was accepted, but the action is not permitted.

    The most common cause is that the resource belongs to a different workspace than the one your key is bound to. Each key is workspace-scoped and can only see resources in its own workspace.
  </Accordion>

  <Accordion title="Are API keys rate limited?">
    Yes. Requests are rate limited per API key.

    If you hit the limit, reduce request frequency and retry with backoff. [Learn more](/api-scope-rate-limits)
  </Accordion>

  <Accordion title="Can I delete an API key?">
    Keys are revoked rather than hard-deleted. This preserves audit visibility.

    Once revoked, the key can no longer be used.
  </Accordion>
</AccordionGroup>

***

## Related posts

* [Quickstart](/quickstart)
* [API reference](/api-reference)
* [Error codes](/error-codes)