# Authentication

> API keys for servers, the same key for MCP, and how errors tell you what to do.

## API keys

Server integrations authenticate with a project API key: `Authorization: Bearer gln_…`. A key belongs to one project and one environment (`gln_test_…` or `gln_live_…`) and carries scopes. Create it in the console (API keys › new): the secret is shown **once**; Galon stores only its SHA-256.

Give each key only the scopes it needs. Revoke a key in the console; rolling a key issues a new secret and revokes the old one at once.

**Check a key**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_test_..."
curl -sS "$GALON_API_BASE/tools" -H "Authorization: Bearer $GALON_API_KEY"
```

`GET /v1/tools` returns `tools`, `project_id` and `environment`: what this key can call.

## Scopes

- `mail:send`
- `contact:read`
- `contact:write`
- `template:read`
- `template:write`
- `validation:check`
- `build:create`
- `build:android`
- `build:read`
- `build:cancel`
- `artifact:read`
- `source:publish`
- `deploy:create`
- `database:create`
- `job:read`
- `job:cancel`
- `usage:read`
- `domain:lookup`
- `domain:quote`
- `domain:read`
- `domain:purchase`
- `domain:transfer`
- `domain:renew`
- `domain:restore`
- `domain:update`
- `domain:dns_read`
- `domain:dns_write`
- `domain:connect`

## Errors and next_action

Every error is `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is one of a closed list; `hint` says what to do; `docs_url` points here; `console_url` appears when a person must act. Error responses carry `X-Request-Id`: quote it to support.

| Status | Code | next_action |
|---|---|---|
| 401 | `api_key_missing` | `use_valid_api_key` |
| 401 | `api_key_invalid` | `use_valid_api_key` |
| 403 | `scope_missing` | `add_missing_scope` |
| 422 | `api_key_environment_mismatch` | `fix_request` |
| 409 | `idempotency_conflict` | `resolve_conflict` |
| 429 | `rate_limited` | `retry_after_delay` |
| 500 | `internal_error` | `retry_later` |

## MCP with an API key

The MCP endpoint `https://api.galon.ai/v1/mcp` (Streamable HTTP, JSON-RPC 2.0: `initialize`, `ping`, `tools/list`, `tools/call`) takes the same key, scopes and limits as the REST API. `tools/list` shows only the tools this key can call. Setup for each assistant: [AI assistants](/cloud/docs/ai-assistants).

**Claude Code**

```bash
claude mcp add --transport http galon https://api.galon.ai/v1/mcp \
  --header "Authorization: Bearer $GALON_API_KEY"
```

## MCP with OAuth (no key)

An MCP client can connect without a key: it discovers the authorisation server from `/.well-known/oauth-protected-resource`, registers itself (dynamic registration), and a person signs in and approves its scopes and a spending limit. PKCE (S256) is required; access tokens last 15 minutes and refresh tokens 30 days, rotated.

An app connected this way asks a person to approve an irreversible action (a purchase, a promotion) with the MCP tool `request_approval`, then waits.
