Create an API key

POST

/v1/api-keys

curl --request POST \
  --url http://localhost:8080/v1/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "key_type": "secret", "expires_at": "2026-04-15T12:00:00Z" }'

• Local development

Creates a key in the caller’s mode: a test-mode caller gets a test key, a live-mode caller gets a live key. The full key (raw_key) is returned once and is never shown again. Hardcount stores only a salted hash. key_type defaults to secret.

A platform key can only be issued by an existing platform key. Platform keys do not hold the apikey:write permission this route needs, so in practice this route never issues one (403). Writes an audit row (never the key value).

Authorizations

• BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

name

required

Label shown in the key list. Must not be blank.

string

key_type

string

default: secret

Allowed values: secret platform

expires_at

Optional. Must be in the future. Omit for a key that does not expire.

string format: date-time

Responses

201

Key created. raw_key is shown only in this response.

Media typeapplication/json

object

key

required

object

id

required

string

key_prefix

required

The start of the key (type, mode and a few characters), enough to tell keys apart. Never the full key.

string

key_type

required

string

Allowed values: platform secret

livemode

required

boolean

name

required

string

tenant_id

required

string

created_at

required

string format: date-time

expires_at

When the key stops working. Also set on the old key during a rotation grace period.

string format: date-time

revoked_at

string format: date-time

last_used_at

Updated at most about once per interval, so it can lag a little.

string format: date-time

raw_key

required

The full key. Shown only once; store it now.

string

Example

{
  "key": {
    "id": "hc_key_1a2b3c4d5e6f7890",
    "key_prefix": "hc_secret_test_1a2b3c4d",
    "key_type": "platform"
  },
  "raw_key": "hc_secret_test_4f9c..."
}

400

Body is not valid JSON

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

403

Caller lacks the apikey:write permission, or asked for a platform key

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

name missing, unknown key_type, or expires_at not in the future

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}