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

# Authentication

> How Archal preserves service Authorization headers, injects bootstrap tokens, and lets agents use normal SDKs and auth flows against clones safely.

## How it works

In controlled runs, your agent keeps using normal service SDKs and auth headers.
Archal authenticates the outer route on a private route header, preserves the
outgoing `Authorization` header as the service credential, and routes the
request to the matching clone.

If a request has no `Authorization` header, Archal's proxy injects a default
bootstrap token before the clone sees it. This **header auto-injection** only
happens on the controlled proxy path - `archal run` with `--docker`/`--sandbox`.
Separately, on any local `archal run` the CLI stamps bootstrap tokens (e.g.
`GITHUB_TOKEN`) into the harness *environment*, so SDKs that read those env vars
send a real `Authorization` header on their own. Either way, most agents using
normal SDKs need no token setup.

**Direct clone calls do not auto-inject.** When you call a clone's REST API
yourself - a local (no-Docker) harness using `AGENT_CLONE_URLS`, an
`archal clone start` session, or any direct HTTP - send the service
`Authorization` header explicitly alongside `x-route-authorization`. An endpoint
that requires auth (for example GitHub's `/user/*`) returns the real service's
401/403 shape when it is missing. Use the bootstrap token below, e.g.
`Authorization: Bearer ghp_AaBb…`. See [Direct API access](/guides/direct-api-access).

## Bootstrap tokens by clone

Use these dummy values when you need to set a token yourself. Real services reject them.

| Clone    | Authorization header                                                                                      | Env vars stamped into the harness                                        |
| -------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| GitHub   | `Bearer ghp_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTt`                                                     | `GITHUB_TOKEN`                                                           |
| Slack    | `Bearer xoxb-123456789012-234567890123-AbCdEfGhIjKlMnOpQrStUvWx`                                          | `SLACK_TOKEN`, `SLACK_BOT_TOKEN`                                         |
| Jira     | `Bearer ATATT3xFfGF0Z1RN2k8B3CdE4FgH5IjK6LmN7OpQ8RsT`                                                     | `JIRA_API_TOKEN` plus `JIRA_EMAIL=agent@acme.com`                        |
| Stripe   | `Bearer sk_live_51Abc123DefGhiJklMnoPqrStUvWxYz0123456789`                                                | `STRIPE_API_KEY`                                                         |
| Linear   | `Bearer lin_api_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTt`                                                 | `LINEAR_API_KEY`                                                         |
| Discord  | `Bot MTAxMjM0NTY3ODkwMTIzNDU2.GT0eVQ.xYzAbCdEfGhIjKlMnOpQrStUvWx`                                         | `DISCORD_TOKEN`                                                          |
| Apify    | `Bearer apify_api_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTt`                                               | `APIFY_TOKEN`, `APIFY_API_KEY`                                           |
| Supabase | `Bearer eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c` | `SUPABASE_SERVICE_ROLE_KEY` plus `SUPABASE_URL=https://acme.supabase.co` |

These values come from the shared clone auth contract. Clones without a listed
bootstrap token require the service-shaped auth their direct API docs describe.

## Overriding tokens

Overrides are rare. Use one only when scenario logic depends on the token value
or your harness sets its own `Authorization` header.

Set the env var in your harness or `.archal.json`:

```bash theme={null}
GITHUB_TOKEN=ghp_your_real_looking_test_value archal run scenario.md --docker
```

Or in `.archal.json`:

```json theme={null}
{
  "agent": {
    "command": "node",
    "args": ["agent.mjs"],
    "env": {
      "GITHUB_TOKEN": "ghp_your_real_looking_test_value"
    }
  }
}
```

<Warning>
  Bootstrap tokens are dummy credentials. They authenticate only against service
  clones - submitting them to real GitHub, Slack, Stripe, etc. will be rejected
  immediately.
</Warning>