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

# Authentication

> Ed25519 assertion JWT, agent access token, shared JWKS.

# Authentication

1. You sign a short **assertion** JWT with your Ed25519 private key
2. Auth returns a short-lived **access** token (EdDSA, IMBA keys, `typ=agent`)
3. You call retail `/api/*` with `Authorization: Bearer <access_token>`

Human Wallet HS256 tokens and Partner access tokens are **not** accepted on the agent money path.

## Assertion → access token

```http theme={null}
POST https://imbawallet.com/auth/v1/agent/token
Content-Type: application/json

{ "assertion": "<JWT>" }
```

### Assertion claims

| Claim          | Required | Notes                                  |
| -------------- | -------- | -------------------------------------- |
| `iss`          | yes      | Decimal text `client_id` from register |
| `aud`          | yes      | Always `imba-agent-api`                |
| `iat` / `exp`  | yes      | Max **60s** lifetime                   |
| `kid` (header) | yes      | Key id from register                   |
| `alg` (header) | yes      | `EdDSA`                                |

### Access token

| Field       | Value                                                                                 |
| ----------- | ------------------------------------------------------------------------------------- |
| TTL         | \~900 seconds                                                                         |
| `typ`       | `agent`                                                                               |
| `client_id` | This agent only                                                                       |
| Signature   | EdDSA — JWKS `GET https://imbawallet.com/auth/v1/partner/jwks` (same keys as Partner) |

Never send `client_id` in the body to pick another wallet. The JWT is the identity.

## Unavailable (`503`)

| Situation                               | Effect                                                              |
| --------------------------------------- | ------------------------------------------------------------------- |
| Caution **medium**                      | New **register** only                                               |
| **under\_attack** or Agent API disabled | Whole agent channel, including `/auth/v1/agent/token` and `/x402/*` |

## Rate limits (defaults)

| Limit                     | Default |
| ------------------------- | ------- |
| Assertions / kid / minute | 30      |
| Assertions / IP / minute  | 60      |

`429` when exceeded. Back off with jitter. Mint a new assertion when the access token is near expiry — there is no refresh token.