# Agent authentication

Use scoped Bearer keys and wallet signatures without exposing credentials.

AI account registration proves control of a wallet once. Routine API work uses the scoped key returned by registration, not a new wallet signature for every request.

## The two-step registration proof

1. Send the wallet address to `POST /api/v1/agents/accounts/challenge`.
2. Read the returned Terms URL and version. Sign `message` exactly as returned using EIP-191 `personal_sign`.
3. Send `message`, `signature`, and an `agent` profile to `POST /api/v1/agents/accounts`.
4. Save `api_key.secret` privately. It is a one-time secret response.

Challenges use EIP-4361 messages, expire after five minutes, and are single-use. Expired or rejected proofs require a fresh challenge. Profile fields such as name, vendor, and model are self-declared metadata, not authorization or proof of affiliation.

See the [local-signing example](https://docs.amplerun.com/start/agent.md) for a complete registration script. A wallet already bound to a different account type, a suspended account, or an account with incompatible security requirements can be refused; do not bypass the response by repeatedly creating accounts.

## Send the API key

```http
Authorization: Bearer <your API key>
```

Send that header only to a trusted AmpleRun API origin. The recommended machine origin is `https://amplerun-api.spiry.org`; the documentation origin is not an API destination.

| Scope | Intended use |
| --- | --- |
| `renter` | Quotes, reservations, rental control, and supported billing operations |
| `host` | Host enrollment and supported host-management operations |

Scopes do not bypass ownership, balance, account verification, admission, or destination checks. A key with the renter scope can spend the account's prepaid balance; do not describe it as read-only merely because your current code only reads.

## Rotate and recover

Use separate keys for separate integrations. Human account holders can create expiring keys and revoke them in [Account](https://amplerun.com/account#api-keys). Revoke unused keys after testing. Re-registration with the same eligible agent wallet issues a new key for the same account; keep track of issued keys rather than using registration as a polling operation.

For hosted MCP, start a new authenticated connection after signup. For local stdio MCP, the current implementation can adopt the issued key in the running process. Persist it securely for the next process start.

Never log complete registration responses, access responses, request headers, wallet keys, or shell environment dumps. Support needs request IDs and error codes, not secrets.

---
Last reviewed: 2026-10-19.
Canonical: https://docs.amplerun.com/agents/authentication/