> ## 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

> Keep the workspace control-plane key separate from short-lived provider credentials.

Archal has two credential boundaries. They are intentionally not interchangeable.
Keep workspace control-plane authority separate from provider credentials.

## Workspace control-plane key

Create a key in **Dashboard > API keys**. It belongs to one workspace and can
be restricted to selected environments and lifecycle scopes.

```bash theme={null}
export ARCHAL_API_KEY=archal_ws_<your-key>
```

Send it as a bearer credential to catalog, sandbox, state, and evidence endpoints:

```bash theme={null}
curl https://api.archal.ai/api/environments \
  --header "authorization: Bearer $ARCHAL_API_KEY"
```

## Provider data-plane credential

When an environment becomes ready, its connection includes:

```json theme={null}
{
  "apiBaseUrl": "https://api.archal.ai/v1/sessions/.../environments/github/api",
  "mcpUrl": "https://api.archal.ai/v1/sessions/.../environments/github/mcp",
  "credentials": {
    "kind": "provider",
    "expiresAt": "2026-08-04T20:00:00.000Z",
    "headers": {
      "authorization": "Bearer <scoped-provider-credential>"
    }
  }
}
```

Read this map from `environments[id].credentials.headers` and apply it exactly
to calls sent to `apiBaseUrl` or `mcpUrl`. Header names vary by provider. The
TypeScript client applies them automatically.

Each credential is bound to one workspace, session, environment, and expiration.

The gateway rejects the workspace key and real upstream-provider credentials. It
also rejects Archal credentials scoped to another sandbox or environment.

## Key handling

* use separate keys for local development, coding-agent pairing, and CI
* enable only the environments and scopes each key needs
* store keys in a protected credential store or secret manager
* never put a key in a URL, repository, client bundle, prompt, or test log
* keep the workspace key out of the process being tested
* revoke an exposed key immediately

Renewal can rotate provider credentials. Refresh application configuration from
the renewed environment connections.