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

# Authentication

> API keys for programmatic access to the UserTrace API

## Overview

The UserTrace API uses long-lived **API keys** for programmatic access from a script, a
CI job, or your agent's production runtime, where a short-lived dashboard session is
impractical.

A key grants **exactly its owner's access**: the same organization, the same scoped
environments. Creating a key never widens what someone can see.

## Base URL

```
https://api.getusertrace.com
```

## Creating a key

Keys are created in the dashboard.

<Steps>
  <Step title="Open the Agent Setup page and scroll to the bottom">
    The **API key** panel is the last section on the page.
  </Step>

  <Step title="Click Create API Key">
    Give it a name that says where it runs, such as `CI reporting` or `prod-agent`, so
    you know what you're revoking later.
  </Step>

  <Step title="Copy the key immediately">
    The full key is shown **exactly once**. Only a hash is stored, so it cannot be
    recovered afterwards.
  </Step>
</Steps>

<Warning>
  If you lose a key, you cannot look it up. Revoke it and create another.
</Warning>

The panel lists every key with its prefix, when it was created, when it was last used, and
its status. **Revoke** takes effect on the very next request.

<Note>
  **Maximum 10 active keys.** Revoked keys stay in the list as history and don't count
  toward the limit.
</Note>

<Note>
  **"Last used" lags by up to an hour.** It's written at most once per hour to keep the
  write off the request path, and stays empty until the key's first use, so a key you
  just used may still show `—`.
</Note>

## Using a key

Pass it in the `x-usertrace-api-key` header. No `Authorization` header is needed.

```bash theme={null}
curl -X GET "https://api.getusertrace.com/api/simulations/sessions/?limit=20" \
  -H "x-usertrace-api-key: ut_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json"
```

## What a key can access

Keys work only on endpoints that explicitly opt in:

| Endpoint                                  | Purpose                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /api/simulations/sessions/`          | [Simulation results](/api-reference/endpoint/simulation-sessions)                  |
| `GET /api/prod-evaluations/sessions/`     | [Production results](/api-reference/endpoint/production-sessions)                  |
| `POST /v1/traces`                         | [Live trace ingestion](/api-reference/endpoint/live-traces)                        |
| `POST /v1/sessions/{conversation_id}/end` | [Close a conversation](/api-reference/endpoint/live-traces#closing-a-conversation) |

Every other endpoint rejects a key with `401`, including the API-key management
endpoints themselves, so a leaked key cannot mint more keys.

## Rate limits

**120 requests per minute, per key.** Exceeding it returns `429` with a `Retry-After`
header giving the seconds until the window resets:

```json theme={null}
{ "message": "API key rate limit exceeded" }
```

The window is fixed rather than sliding, so a burst spanning a minute boundary can briefly
reach twice the limit. Dashboard-authenticated requests are not rate limited.

## Errors

| Response                                           | Meaning                                                    |
| -------------------------------------------------- | ---------------------------------------------------------- |
| `401 {"message": "Invalid API key"}`               | Unknown, revoked, or the owner's access no longer resolves |
| `401 {"message": "Authorization header required"}` | The `x-usertrace-api-key` header is missing                |
| `401` on any other endpoint                        | That endpoint is not one of the four above                 |
| `429 {"message": "API key rate limit exceeded"}`   | 120/min per key exceeded; see `Retry-After`                |