Every metered endpoint under `/api/v1` takes a 1ToolRing API key, preferably in the `Authorization` header. The catalog endpoints are public and need no key.

```http
Authorization: Bearer aip_live_...
```

Email verification also accepts the legacy `x-api-key: <key>` header. Routed `toolring.<capability>` calls and gateway tools read the key from `x-api-key`; sending the same key in both headers is safe. The MCP server accepts Bearer only.

## Creating a key

Keys are created in the dashboard under **API keys**. A verified email is required. The raw key is returned once and never shown again.

## Using a key

```bash
curl "https://api.1toolring.com/api/v1/email/verify/credits" \
  -H "Authorization: Bearer $TOOLRING_KEY"
```

## Key lifecycle

- **Revoke** from the dashboard. A revoked key stops working immediately.
- **Scope and caps.** A key belongs to one user; it can carry a credit cap, a call cap, and deny rules for hosts, paths or methods.
- **Hashing.** 1ToolRing stores only `sha256(key)`; the raw key cannot be recovered after creation.

## Errors

| Code | Status | Meaning |
| --- | --- | --- |
| `UNAUTHORIZED` | 401 | Missing or malformed credential. |
| `INVALID_API_KEY` | 401 | Key not found or revoked. |
| `RATE_LIMITED` | 429 | Request limit for this key exceeded. |
| `INSUFFICIENT_CREDITS` | 402 | The wallet cannot cover this call. |
| `BUDGET_EXCEEDED` | 402 | A credit cap on the key, org or agent would be exceeded. |
| `CALL_CAP_EXCEEDED` | 402 | The call cap for this key has been reached. |
| `POLICY_DENIED` | 402 | A deny rule blocked this host, path or method. |
| `PAYMENT_REQUIRED` | 402 | x402 offer issued; see [x402](/authentication/x402). |