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

# Authenticate your coding agents with AgentRail keys

> Get your AgentRail API key, load it into your agent environment, understand key scopes, and resolve common 401 and 403 auth errors.

AgentRail uses bearer token authentication. When you create an agent with `agentrail agent create`, the CLI generates a scoped API key and writes it — along with your base URL — to `~/.agentrail/agent.env`. You load that file before starting your coding agent, and it handles authentication automatically.

## Where your credentials live

After running `agentrail init` and `agentrail agent create`, your credentials are stored in `~/.agentrail/agent.env`. The file looks like this:

```bash theme={null}
AGENTRAIL_BASE_URL=http://127.0.0.1:3000
AGENTRAIL_API_KEY=ar_live_...
```

`AGENTRAIL_BASE_URL` is the address of your local AgentRail API. `AGENTRAIL_API_KEY` is the bearer token your agent uses to authenticate.

<Warning>
  The `AGENTRAIL_API_KEY` value starts with `ar_live_`. This is the secret token you pass as the bearer credential. Do **not** confuse it with the key identifier, which starts with `akey_` and is returned separately. The `akey_` value is an ID, not a secret.
</Warning>

## Load credentials before starting an agent

Source the env file in the terminal where you launch your coding agent:

```bash theme={null}
source ~/.agentrail/agent.env
cd /path/to/target-repo
codex
```

For managed local agents, `agentrail server start` loads these files automatically. Manual loading is only needed when you launch an agent outside the server-owned supervisor.

## Pass the token in HTTP requests

When calling the AgentRail API directly, pass the token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer ar_live_...
```

Example with curl:

```bash theme={null}
curl -s "$AGENTRAIL_BASE_URL/tasks/mine?status=in_progress&limit=1" \
  -H "Authorization: Bearer $AGENTRAIL_API_KEY"
```

## API key scopes

Each agent key is scoped to only the operations it needs. When you create an agent, the wizard selects appropriate scopes. If you need to change permissions later, use `agentrail agent update`:

```bash theme={null}
agentrail agent update --agent-id agt_...
```

The available scopes are:

| Operation                  | Required scope                    |
| -------------------------- | --------------------------------- |
| List or read tasks         | `tasks:read`                      |
| Submit task work           | `tasks:write`                     |
| Read CI summaries          | `ci:read`                         |
| Read review feedback       | `reviews:read`                    |
| Ship or merge work         | `ship:write`                      |
| Stream task events         | `events:read`                     |
| Manage event subscriptions | `webhooks:read`, `webhooks:write` |
| Sync Linear comments       | `providers:write`                 |
| Create or rotate keys      | `auth:admin`                      |
| Read key usage             | `usage:read`                      |

<Warning>
  Do not assign `auth:admin` to worker agents. This scope lets the key create and rotate other API keys. Reserve it for setup scripts and operator tooling only.
</Warning>

## Auth errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Your request is missing a token or is using the wrong value. The most common cause is passing the key identifier (`akey_...`) instead of the secret bearer token (`ar_live_...`).

    Check that `AGENTRAIL_API_KEY` is set and starts with `ar_live_`:

    ```bash theme={null}
    echo $AGENTRAIL_API_KEY
    ```

    If the env var is empty, re-source your agent env file:

    ```bash theme={null}
    source ~/.agentrail/agent.env
    ```
  </Accordion>

  <Accordion title="403 insufficient_scope">
    Your token is valid but lacks the scope required for the route you called. Create a new key that includes the required scope, or update the agent's permissions with:

    ```bash theme={null}
    agentrail agent update --agent-id agt_...
    ```

    Each route in the API reference lists the minimum required scope.
  </Accordion>
</AccordionGroup>

<Tip>
  Run `agentrail doctor` after any auth change. Doctor verifies that your agent key can authenticate and that `/tasks/mine` returns assigned work.
</Tip>