# Create key

> Create an inference key with a management key. The secret is returned once.

`POST https://api.numes.ai/api/v1/keys`

Source: https://0.0.0.0:3000/docs/api-reference/keys/create-key
Authorization: Bearer management key

`billing_currency` is required, must be enabled for the account, and can never change. `limit_reset` requires a `limit`; `expires_at` must be a future UTC timestamp. Store the returned `key` immediately — it is never shown again. Guide: [Management keys](/docs/account/management-keys).

```request
{
  "method": "POST",
  "path": "/keys",
  "auth": "management",
  "body": {
    "name": "Customer 1042",
    "billing_currency": "USD",
    "limit": 25,
    "limit_reset": "monthly",
    "expires_at": "2027-01-01T00:00:00Z"
  }
}
```

```json title="Response 201"
{
  "data": {
    "hash": "5d41402abc4b2a76b9719d911017c592ae2f5e8f5d9c4b1e0a3f6e7d8c9b0a1f",
    "label": "sk-...-v1-3f9a...c21e",
    "name": "Customer 1042",
    "billing_currency": "USD",
    "disabled": false,
    "limit": 25,
    "limit_remaining": 25,
    "limit_reset": "monthly",
    "usage": 0,
    "usage_daily": 0,
    "usage_weekly": 0,
    "usage_monthly": 0,
    "created_at": "2026-09-28T12:00:00Z",
    "updated_at": null,
    "expires_at": "2027-01-01T00:00:00Z"
  },
  "key": "sk-...-v1-…"
}
```

## Headers

- `X-Request-Id` (string; Length 1–128): Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

## Request body (application/json)

- `name` (string; required; Length 1–100)
- `billing_currency` (enum<string>; required; one of USD, BTC): Required, non-null immutable settlement currency for the inference key. Must be enabled for new operations.
- `limit` (number | null; Range ≥ 0)
- `limit_reset` (enum<string> | null; one of daily, weekly, monthly)
- `expires_at` (string<date-time> | null)

## Response 201 (application/json)

- `data` (object; required)
  - `hash` (string; required)
  - `label` (string; required)
  - `name` (string; required)
  - `billing_currency` (enum<string>; one of USD, BTC): Immutable settlement currency; omitted for management keys.
  - `disabled` (boolean; required)
  - `limit` (number | null; required)
  - `limit_remaining` (number | null; required)
  - `limit_reset` (enum<string> | null; required; one of daily, weekly, monthly)
  - `usage` (number; required)
  - `usage_daily` (number; required)
  - `usage_weekly` (number; required)
  - `usage_monthly` (number; required)
  - `created_at` (string<date-time>; required)
  - `updated_at` (string<date-time> | null; required)
  - `expires_at` (string<date-time> | null; required)
- `key` (string; required): One-time plaintext key secret.

## Response default (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)