# Key info

> GET /key reference: read a key's organization, project, status, spend limit, expiry and spend with the key itself. Its error body is {message, code} and every rejected key gets 401.

Source: https://kiln.bricksum.com/docs/en/api-reference/key

`GET https://api.bricksum.com/v1/key`

Returns the organization, project, status, spend limit, expiry and spend so far of the API key that makes the call. It is the way to read a key without a console account: a teammate who holds a key can check it. The plaintext key and its hash are not part of the response.

What the spend limit and the monthly budget do is on the [Usage & billing](https://kiln.bricksum.com/docs/en/usage-billing) page.

The base URL, the other endpoints and the limits they share are on the [API Reference](https://kiln.bricksum.com/docs/en/api-reference) page.

## Authentication

Send the API key itself as a Bearer token: Authorization: Bearer sk-bk-your-key. The identity on this route is the key, so a console session token is not accepted. This endpoint is not part of the inference gateway: it is served by the Kiln API, which looks the key up by its hash and answers 401 for anything it cannot resolve to an active key.

## Request

| Status | Description |
| --- | --- |
| supported | The gateway handles it, or a published measurement shows it works. |
| passed through | Forwarded to the model server; not verified by Kiln. |
| ignored | Accepted with 200, but not applied. The rest of the response is normal. |
| not supported | Rejected with an error, or not working on the models named in the description. |

| Field | Type | required | Default | Status | Description |
| --- | --- | --- | --- | --- | --- |
| `Authorization` | header | required |  | supported | Bearer token holding the API key, for example Authorization: Bearer sk-bk-your-key. The value is checked for the key prefix and length before the lookup, so a console session token (a JWT) is rejected with 401 (unauthorized). |
| `x-api-key` | header |  |  | not supported | Not read on this route. A request that carries only x-api-key is answered 401 (unauthorized), even when the value is a valid key. Use Authorization. |
| `x-org-id` | header |  |  | ignored | The identity headers x-org-id, x-project-id and x-api-key-id are removed by the gateway on this route. The organization and project of the response come from the key, not from a header. |
| `query string` | string |  |  | ignored | The endpoint takes no parameters. A query string is accepted and has no effect on the response. |

The key in the Authorization header selects the record. There is nothing else to send.

## Response body

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Key ID (UUID). The console shows the same ID on the key row. |
| `org_id` | string | ID of the organization the key belongs to. Usage on this key is charged to that organization. |
| `project_id` | string | ID of the project the key belongs to. |
| `name` | string | Name given to the key in the console. |
| `prefix` | string | Key prefix, sk-bk-. It is the same for every key. |
| `last4` | string | Last four characters of the key, for telling keys apart in a list. The full key is shown once at creation and is not retrievable afterwards. |
| `status` | string | Key status. A successful response carries "active": a suspended or revoked key is answered 401 instead. |
| `spend_limit_usd` | number \| null | Spend limit of this key in USD. null means the key has no limit of its own. Once the limit is reached, inference requests with this key are rejected with 402. |
| `expires_at` | string \| null | Expiry as an RFC 3339 timestamp, or null when the key does not expire. From that moment the key is answered 401 here and on the inference endpoints. |
| `usage_usd` | number | Spend recorded for this key in USD, summed from its usage events. It is what the spend limit is compared against. |
| `last_used_at` | string \| null | When the key was last accepted by the gateway, as an RFC 3339 timestamp, or null when it has not been used. The gateway stamps it outside the request path, so a very recent call can still be missing. |
| `created_at` | string | When the key was created, as an RFC 3339 timestamp. |

## Errors

This endpoint is served by the Kiln API, not by the inference gateway, so its error body is {"error": {"message", "code"}}. There is no type or param field, and error.code is a short string such as unauthorized. Branch on the HTTP status and error.code, not on the message text.

| Status | error.code | Cause | What to do |
| --- | --- | --- | --- |
| 401 | `unauthorized` | The Authorization header is missing, is not a Bearer token, or its value is not shaped like an API key. A console session token falls in this case. The message is API key required. | Send Authorization: Bearer with an API key created in the console. |
| 401 | `unauthorized` | The key is unknown, or it is not active (suspended or revoked), or its expiry has passed. All three answer the same 401 with the message invalid API key, so the response does not say which case it was. | Check the key's status and expiry in the console, or create a new key. |
| 429 |  | The shared gateway limit on this route, counted across all callers rather than per organization. The gateway produces this response itself, so it does not carry the error shape above and may have no body at all. | Back off and retry. Do not parse the body; branch on the status alone. |
| 500 | `internal` | The key store could not be read. The message is internal error. | Retry after a short wait, and check the status page. |

Every status code is listed on the [Errors](https://kiln.bricksum.com/docs/en/errors) page.

## Limits

- Billing: not billed. This endpoint runs no inference, so it publishes no usage event and does not move usage_usd.
- Scope: the response describes the key in the Authorization header and no other key. There is no endpoint that lists an organization's keys with this authentication.
- Rate limit: the gateway applies a shared limit to this route, counted across all callers rather than per organization. A 429 from that limit is produced by the gateway, so its body is not the shape described above.
- No SDK covers this endpoint: it is not part of the OpenAI or Anthropic API, so the SDKs have no method for it. Call it with an HTTP client.

Headers and retry guidance for 429 are on the [Rate limits](https://kiln.bricksum.com/docs/en/rate-limits) page.

## Examples

### Request

**cURL**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer $KILN_API_KEY"
```

### Response

**200 OK**
```json
{
  "id": "6f1c2e7a-3c4d-4a10-9a2b-0f5c8d7e1234",
  "org_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
  "project_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
  "name": "production",
  "prefix": "sk-bk-",
  "last4": "9f3c",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": "2027-01-01T00:00:00Z",
  "usage_usd": 12.34,
  "last_used_at": "2026-09-18T07:21:03Z",
  "created_at": "2026-06-01T09:00:00Z"
}
```

**401 Unauthorized**
```json
{
  "error": {
    "message": "invalid API key",
    "code": "unauthorized"
  }
}
```