---
title: "Create a new API key"
method: POST
path: "/keys"
tags: ["API Keys"]
---

# Create a new API key

`POST /keys`

Create a new API key for the authenticated user. The plaintext `key` is returned only in this response. Treat it as a write-only, sensitive value; it cannot be retrieved later. [Management key](/docs/guides/overview/auth/management-api-keys) required.

## Request body

- object
  - `creator_user_id` string, nullable — Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key.
  - `expires_at` string, date-time, nullable — Optional ISO 8601 UTC timestamp when the API key should expire. Must be UTC, other timezones will be rejected
  - `include_byok_in_limit` boolean — Whether to include BYOK usage in the limit
  - `limit` number, double, nullable — Optional spending limit for the API key in USD
  - `limit_reset` 'daily' | 'weekly' | 'monthly' | 'null', nullable — Type of limit reset for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday.
  - `name` string, required — Name for the new API key
  - `workspace_id` string, uuid — The workspace to create the API key in. Defaults to the default workspace if not provided.

## Response `201`

API key created successfully

- object
  - `data` object, required — The created API key information
    - `byok_usage` number, double, required — Total external BYOK usage (in USD) for the API key
    - `byok_usage_daily` number, double, required — External BYOK usage (in USD) for the current UTC day
    - `byok_usage_monthly` number, double, required — External BYOK usage (in USD) for current UTC month
    - `byok_usage_weekly` number, double, required — External BYOK usage (in USD) for the current UTC week (Monday-Sunday)
    - `created_at` string, required — ISO 8601 timestamp of when the API key was created
    - `creator_user_id` string, nullable, required — The user ID of the key creator. For organization-owned keys, this is the member who created the key. For individual users, this is the user's own ID.
    - `disabled` boolean, required — Whether the API key is disabled
    - `expires_at` string, date-time, nullable — ISO 8601 UTC timestamp when the API key expires, or null if no expiration
    - `hash` string, required — Unique hash identifier for the API key
    - `include_byok_in_limit` boolean, required — Whether to include external BYOK usage in the credit limit
    - `label` string, required — Human-readable label for the API key
    - `limit` number, double, nullable, required — Spending limit for the API key in USD
    - `limit_remaining` number, double, nullable, required — Remaining spending limit in USD
    - `limit_reset` string, nullable, required — Type of limit reset for the API key
    - `name` string, required — Name of the API key
    - `updated_at` string, nullable, required — ISO 8601 timestamp of when the API key was last updated
    - `usage` number, double, required — Total OpenRouter credit usage (in USD) for the API key
    - `usage_daily` number, double, required — OpenRouter credit usage (in USD) for the current UTC day
    - `usage_monthly` number, double, required — OpenRouter credit usage (in USD) for the current UTC month
    - `usage_weekly` number, double, required — OpenRouter credit usage (in USD) for the current UTC week (Monday-Sunday)
    - `workspace_id` string, required — The workspace ID this API key belongs to.
  - `key` string, required — The actual API key string (only shown once)

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Authentication successful but insufficient permissions
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error

---

[API](https://skmtc.net/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.net/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/versions/9d1da2c7d2c3/schema)