create-key

Create a new API key for user authentication and authorization. Use this when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace. Important: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved later. Required permissions: Your root key needs one of:

api.*.create_key (create keys in any API)
api.<api_id>.create_key (create keys in a specific API)

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api keys create-key [flags]

Flags

--api-id

string

required

The API namespace this key belongs to. Keys from different APIs cannot access each other.

--prefix

string

Prefix prepended to the generated key string for easier recognition in logs and dashboards (e.g., prod_xxxxxxxxx). Must be 1-16 characters containing only letters, numbers, and underscores.

--name

string

Human-readable name for the key, visible only in management interfaces and API responses. Avoid generic names like “API Key” when managing multiple keys.

--byte-length

integer

Cryptographic key length in bytes. The default of 16 bytes provides 2^128 possible combinations, sufficient for most applications. Minimum 16, maximum 255.

--external-id

string

Your system’s user or entity identifier to link to this key. Returned during verification to identify the key owner without additional database lookups. Accepts letters, numbers, underscores, dots, and hyphens.

--meta-json

string

JSON object of arbitrary metadata returned during key verification. Eliminates additional database lookups during verification, improving performance for stateless services. Avoid storing sensitive data here as it is returned in verification responses.

Show JSON schema

(any key)

any

Arbitrary key-value pairs. The object can contain strings, numbers, booleans, arrays, or nested objects. Keep total size under 10KB for best verification latency.

--roles

string[]

Comma-separated list of role names to assign. Roles must already exist in your workspace. During verification, all permissions from assigned roles are checked against requested permissions.

--permissions

string[]

Comma-separated list of permission names to grant directly to this key. Wildcard permissions like documents.* grant access to all sub-permissions. Direct permissions supplement any permissions inherited from assigned roles.

--expires

integer

Unix timestamp in milliseconds when the key expires. Verification fails with code=EXPIRED immediately after this time passes. Omit to create a permanent key that never expires.

--credits-json

string

JSON object of credit and refill configuration. Controls usage-based limits through credit consumption with optional automatic refills. Unlike rate limits which control frequency, credits control total usage with global consistency.

Show JSON schema

remaining

integer

required

Number of credits remaining. Set to the initial credit balance for the key.

refill

object

Configuration for automatic credit refill behavior.

Show refill properties

interval

string

required

How often credits are automatically refilled. One of daily or monthly.

amount

integer

required

Number of credits to add during each refill cycle. Minimum 1.

refillDay

integer

Day of the month for monthly refills (1-31). Only required when interval is monthly. For days beyond the month’s length, refill occurs on the last day of the month.

--ratelimits-json

string

JSON array of rate limit configurations. Defines time-based rate limits that protect against abuse by controlling request frequency. Unlike credits which track total usage, rate limits reset automatically after each window expires.

Show JSON schema (array of objects)

name

string

required

The name of this rate limit, used to identify which limit to check during key verification. Use descriptive names like api_requests or heavy_operations. 3-128 characters.

limit

integer

required

The maximum number of operations allowed within the specified time window. When reached, verification requests fail with code=RATE_LIMITED until the window resets. Minimum 1.

duration

integer

required

The duration of each rate limit window in milliseconds. Common values: 1000 (1 second), 60000 (1 minute), 3600000 (1 hour), 86400000 (24 hours). Minimum 1000.

autoApply

boolean

required

Whether this rate limit should be automatically applied when verifying a key. Defaults to false.

--enabled

boolean

default:"true"

Whether the key is active for verification. When set to false, all verification attempts fail with code=DISABLED.

--recoverable

boolean

default:"false"

Whether the plaintext key is stored in an encrypted vault for later retrieval. Only enable for development keys or when key recovery is absolutely necessary.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format — use `json` for raw JSON

Examples

unkey api keys create-key --api-id=api_1234abcd

Output

Default output shows the request ID with latency, followed by the created key:

req_2c9a0jf23l4k567 (took 120ms)

{
  "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
  "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
}

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}

Getting Started

Changelog

Framework Guides

Cookbook

API Keys

Rate Limiting

Identities

Analytics

Audit Logs

Security

AI Code Gen

CLI

Migrations

Errors

Usage

Flags

Global Flags

Examples

Output

Getting Started

Changelog

Framework Guides

Cookbook

API Keys

Rate Limiting

Identities

Analytics

Audit Logs

Security

AI Code Gen

CLI

Migrations

Errors

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output