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

# Authentication

> How API keys work and how to send them.

Every request authenticates with an API key. Keys are created in the Clicks app, and each key is bound to exactly one agent.

## Create an API key

<Steps>
  <Step title="Open the API access tab">
    In the Clicks app, open the agent you want to call and go to its **API access** tab.
  </Step>

  <Step title="Create the key">
    Click **Create key** and give it a name you'll recognize later. Use one key per integration, so you can rotate or revoke each one independently.
  </Step>

  <Step title="Store the secret">
    Copy the key (`ak_…`) when it appears — this is the only time the full secret is shown. Store it in a secret manager. The server keeps only a hash, so a lost key can't be recovered, only replaced.
  </Step>
</Steps>

## Send the key

Send the key as a Bearer token on every request:

```bash Authenticate a request theme={null}
curl https://app.us.goclicks.ai/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $CLICKS_API_KEY"
```

The example uses the base URL `https://app.us.goclicks.ai/v1`.

If the `Authorization` header is missing or isn't a Bearer credential, the API also accepts the key in an `X-API-Key` header. If a request includes both, the API uses the Bearer token.

## Scoping

Each key belongs to exactly one organization and one agent. The key determines which agent runs; the request can't override it. If `template_id` doesn't match the key's agent, the API returns `403`. A run that belongs to another organization or agent returns `404`, the same response as a nonexistent ID.

## Key lifecycle

On the same tab, you can disable, re-enable, and delete keys. While a key is disabled, requests fail with `401 Invalid API key`; you can re-enable it later. Deleting a key is permanent. The key's **Last used** timestamp in the app updates within a few seconds of each request. Use it to find keys that are no longer in use. Auth failures are covered in [Errors and retries](/api/errors).

<Warning>
  **Keep keys secure.** Use one key per integration. To rotate a key, create the new key before you delete the old one. Never put keys in browser code or query strings.
</Warning>