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

# Authentication

> How to authenticate with the Inkwell Agent API.

# Authentication

The Inkwell Agent API uses two authentication methods depending on the endpoint.

## API Key (Agent endpoints)

All `/api/v1/ika/agent/*` endpoints require an API key in the `X-API-Key` header. Keys are prefixed with `lev_`.

```bash theme={null}
curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
  -H "X-API-Key: lev_abc123..."
```

You can also use the `Authorization: Bearer` header:

```bash theme={null}
curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
  -H "Authorization: Bearer lev_abc123..."
```

### Getting a key

**Self-register** (no account needed):

```bash theme={null}
curl -X POST https://backend.inkwell.finance/api/v1/agents/self-register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "agentName": "my-staking-bot"
  }'
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "apiKey": "lev_abc123...",
    "keyPrefix": "lev_abc12345",
    "tier": "free",
    "status": "pending_verification",
    "rateLimits": { "rpm": 10, "rpd": 100 },
    "warning": "Store this key securely. It cannot be retrieved again. Check your email to verify and activate it."
  }
}
```

<Warning>
  Your key is returned immediately but **inactive** until you verify your email. Check your inbox for a verification link from Inkwell. The link expires after 24 hours.
</Warning>

<Warning>
  Store your API key securely. It cannot be retrieved after creation. If lost, use key rotation to generate a new one.
</Warning>

### Email verification

After registering, click the verification link sent to your email. You can also verify programmatically:

```bash theme={null}
curl "https://backend.inkwell.finance/api/v1/agents/verify?token=YOUR_VERIFICATION_TOKEN"
```

Until verified, any request using the key will return `401 Unauthorized`.

### Key rotation

```bash theme={null}
curl -X POST https://backend.inkwell.finance/api/v1/agents/{id}/rotate \
  -H "Authorization: Bearer YOUR_JWT"
```

This invalidates the old key immediately and returns a new one.

## Bearer Token (Management endpoints)

Agent management endpoints (`/api/v1/agents/*` except self-register and verify) require a user JWT:

```bash theme={null}
curl https://backend.inkwell.finance/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT"
```

## Public endpoints (no auth)

All `/api/v1/ika/*` endpoints (without `/agent/`) are public and require no authentication:

```bash theme={null}
curl https://backend.inkwell.finance/api/v1/ika/validators
curl https://backend.inkwell.finance/api/v1/ika/price
curl https://backend.inkwell.finance/api/v1/ika/epoch
```

## Rate limits

Rate limit headers are included on every authenticated response:

| Header                  | Description                                  |
| ----------------------- | -------------------------------------------- |
| `X-RateLimit-Remaining` | Requests remaining (min of RPM and RPD)      |
| `X-RateLimit-Reset`     | Unix timestamp when the minute window resets |

When rate limited, the API returns `429 Too Many Requests` with a `Retry-After` header.

Rate limits are **persisted** — restarting the server does not reset your limits.

### Limits by tier

| Tier       | RPM    | RPD    | How to get             |
| ---------- | ------ | ------ | ---------------------- |
| free       | 10     | 100    | Self-register          |
| builder    | 100    | 1,000  | Self-register or admin |
| pro        | Custom | Custom | Admin only             |
| enterprise | Custom | Custom | Admin only             |

Self-registration always creates a free tier key. There is no automatic upgrade — tier promotion requires an admin to re-register the agent via `POST /agents/register`.

### Registration limits

Self-registration is rate limited to prevent abuse:

| Limit            | Value             |
| ---------------- | ----------------- |
| Per IP per hour  | 3 registrations   |
| Per IP per day   | 10 registrations  |
| Global daily cap | 100 registrations |

### Global protection

The API includes a global circuit breaker. If total request volume exceeds 10,000 requests per minute across all agents, the API returns `503 Service Overloaded` until traffic subsides. Individual IP addresses are also throttled at 100 requests per minute regardless of agent identity.

## Error responses

All errors follow a consistent format:

```json theme={null}
{
  "error": "rate_limited",
  "message": "Per-minute rate limit exceeded (10 rpm)",
  "status": 429
}
```

Standard error codes: `invalid_input`, `rate_limited`, `store_not_ready`, `rpc_unavailable`, `not_found`, `unauthorized`, `forbidden`, `timeout`, `service_overloaded`, `internal_error`.