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

# Authentication

> How to authenticate with the Amrood API

# Authentication

Amrood uses API keys for authentication. There are two modes:

## Platform Authentication

Used by developers making server-to-server calls. Grants access to all agents under the platform.

```
x-platform-id: plt_abc123
x-platform-secret: sk_live_xxxxx
```

Platform keys can:

* Create and manage owners
* Create and manage agents
* Access any agent's wallet and transactions
* Update spend policies

## Agent Authentication

Used by AI agents making their own calls. Scoped to a single agent's wallet.

```
x-agent-key: agk_live_xxxxx
```

Agent keys can:

* Check their own balance
* Fund their wallet
* Make payments
* View their transaction history

Agent keys **cannot**:

* Access other agents' data
* Create owners or agents
* Override spend policies

## Owner Session Authentication

Used by account holders to manage their agents, approve transactions, and configure policies.

Authenticate via OTP:

```bash theme={null}
# Send OTP
POST /v1/auth/send-otp
{ "phone": "9876543210" }

# Verify OTP
POST /v1/auth/verify-otp
{ "phone": "9876543210", "code": "123456" }
```

Session cookie (`amrood_session`) is set automatically. Owner session can:

* View and manage their agents
* Approve or reject pending transactions
* Configure organization budgets
* Manage agent certificates

## Admin Authentication

OTP-only access for platform administrators. See [Admin Dashboard](/admin) for details.

## Security

* All API keys are hashed with bcrypt before storage — raw keys are never persisted
* Keys are returned exactly once at creation time
* Rate limiting: 100 req/min per agent, 1000 req/min per platform, 30 req/min unauthenticated
* All transactions require an `idempotency_key` to prevent duplicate processing
* Agent key rotation available via `POST /v1/agents/{agent_id}/rotate-keys`
* Platform-signed network proofs via `GET /v1/agents/me/proof` (Ed25519, 1-hour TTL)

## Error Responses

Invalid or missing credentials return:

```json theme={null}
{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or missing API key"
  }
}
```