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

# Authentication

> Secure your API calls with scoped tokens and understand rate limits.

## Bearer Token

All Unwall API requests require a bearer token in the `Authorization` header. Tokens are project-scoped and prefixed with `aw_live_`.

```bash theme={null}
curl https://api.unwall.xyz/v1/balance \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx"
```

Tokens are SHA-256 hashed before storage -- the plaintext value is never saved on our servers. Each token belongs to exactly one project and can be revoked instantly from the dashboard.

## Permissions

Tokens carry independent permission scopes. Only grant the permissions your agent actually needs.

| Permission | Grants Access To                                                                  |
| ---------- | --------------------------------------------------------------------------------- |
| `read`     | `GET /v1/balance`, `GET /v1/transactions`, `GET /v1/stablecoin/address`           |
| `pay`      | `POST /v1/pay` (fiat + USDC rails), `POST /v1/usdc/transfer`, `POST /v1/payments` |
| `x402`     | `POST /v1/pay` (x402 rail), `POST /v1/x402/pay`                                   |

When creating a token, select only the permissions required:

```bash theme={null}
curl -X POST https://api.unwall.xyz/dashboard/projects/PROJECT_ID/tokens \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read-only-monitor",
    "permissions": ["read"]
  }'
```

<Warning>
  If a token lacks the required permission for an endpoint, the API returns `403 Forbidden` with a message indicating which permission is missing.
</Warning>

## Rate Limits

Agent API tokens are rate-limited to **100 requests per minute** using a sliding window. When the limit is exceeded, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait.

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 12 seconds."
}
```

## Error Responses

| Status Code             | Meaning                  | When It Happens                                                                       |
| ----------------------- | ------------------------ | ------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | Invalid or missing token | The `Authorization` header is absent, malformed, or contains a revoked/invalid token. |
| `403 Forbidden`         | Insufficient permissions | The token is valid but does not have the required permission scope for the endpoint.  |
| `429 Too Many Requests` | Rate limited             | The token has exceeded 100 requests per minute. Check the `Retry-After` header.       |

### Example error response

```json theme={null}
{
  "detail": "Token does not have the required permission: pay"
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store tokens in environment variables">
    Never hard-code tokens in source code or commit them to version control. Use environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your platform's built-in secret store.
  </Accordion>

  <Accordion title="Use least-privilege permissions">
    Only grant the permissions your agent actually needs. A monitoring agent should have `read` only. A payment agent might need `read` + `pay`. Only grant `x402` to agents that call x402-enabled APIs.
  </Accordion>

  <Accordion title="Rotate tokens regularly">
    Create new tokens and revoke old ones on a regular cadence. You can have multiple active tokens per project, making zero-downtime rotation straightforward.
  </Accordion>

  <Accordion title="Set token expiry">
    When creating tokens, set an expiration date for short-lived use cases. Expired tokens are automatically rejected without needing manual revocation.
  </Accordion>
</AccordionGroup>