API keys

The API keys endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

Endpoint	What it does
GET `/v1/api_keys`	List the API keys of the calling key's mode, newest first.
POST `/v1/api_keys`	Create an API key in the calling key's mode. The response is the only place a secret key's token appears.
GET `/v1/api_keys/{id}`	Retrieve an API key.
POST `/v1/api_keys/{id}/roll`	Replace an API key with a new one of the same access. The old key ends now, or after expires_in seconds.
POST `/v1/api_keys/{id}/revoke`	Revoke an API key at once. Revoking a revoked key returns it unchanged.

The API key object

Field	Type	About
`id`	string	An id that starts `key_`.
`object`	string	Always `"api_key"`.
`type`	enum	One of `secret`, `restricted`, `publishable`.
`livemode`	boolean
`label`	string or null
`display`	string
`token`	string
`scopes`	array of string or null
`allowed_origins`	array of string or null	Where a publishable key's card form may be embedded. null for every other kind of key.
`status`	enum	One of `active`, `expiring`, `revoked`.
`api_version`	enum	One of `2026-11-06`.
`expires_at`	integer or null	Unix seconds.
`revoked_at`	integer or null	Unix seconds.
`created`	integer	Unix seconds.

{
  "id": "key_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "api_key",
  "type": "secret",
  "livemode": false,
  "label": "Order server",
  "display": "kashu_sk_test_4eC3...0aaa",
  "scopes": [
    "payments:read"
  ],
  "allowed_origins": [
    "https://shop.example.com"
  ],
  "status": "active",
  "api_version": "2026-11-06",
  "expires_at": null,
  "revoked_at": null,
  "created": 1762473600
}

GET `/v1/api_keys`

List the API keys of the calling key's mode, newest first.

Scope: api_keys:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with a list of API key, newest first.

Parameters

Name	In	Type	Required	About
`limit`	query	integer	Optional	At least 1. Up to 100. Defaults to `10`.
`cursor`	query	string	Optional
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_missing`, `parameter_invalid`, `parameter_unknown`, `cursor_invalid`, `cursor_expired`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
500	`api_error`

Examples

curl "https://api.kashupay.com/v1/api_keys?limit=3" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const list = await kashu("GET", "/v1/api_keys?limit=3");
console.log(list.has_more);

POST `/v1/api_keys`

Create an API key in the calling key's mode. The response is the only place a secret key's token appears.

Scope: api_keys:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 201 with the API key.

Parameters

Name	In	Type	Required	About
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`type`	enum	Required	One of `secret`, `restricted`, `publishable`.
`scopes`	array of string	Optional	Up to 50 items.
`allowed_origins`	array of string	Optional	Publishable keys only: the origins (https://shop.example.com) the card form may be embedded on. A test key may also name http://localhost or http://127.0.0.1, with a port. Without any, the card form refuses to load. Up to 20 items.
`label`	string	Optional	Up to 100 characters.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/api_keys \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"secret","label":"Order server"}'

const apiKey = await kashu("POST", "/v1/api_keys", {
  "type": "secret",
  "label": "Order server"
});
console.log(apiKey.status);

GET `/v1/api_keys/{id}`

Retrieve an API key.

Scope: api_keys:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with the API key.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `key_`.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_unknown`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const apiKey = await kashu("GET", "/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(apiKey.status);

POST `/v1/api_keys/{id}/roll`

Replace an API key with a new one of the same access. The old key ends now, or after expires_in seconds.

Scope: api_keys:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the API key.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `key_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`expires_in`	integer	Optional	Up to 604800.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L/roll \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in":86400}'

const apiKey = await kashu("POST", "/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L/roll", {
  "expires_in": 86400
});
console.log(apiKey.status);

POST `/v1/api_keys/{id}/revoke`

Revoke an API key at once. Revoking a revoked key returns it unchanged.

Scope: api_keys:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the API key.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `key_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L/revoke \
  -X POST \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const apiKey = await kashu("POST", "/v1/api_keys/key_1a2B3c4D5e6F7g8H9i0J1k2L/revoke");
console.log(apiKey.status);

API keys

The API key object

GET /v1/api_keys

Parameters

Errors

Examples

POST /v1/api_keys

Parameters

Request body

Errors

Examples

GET /v1/api_keys/{id}

Parameters

Errors

Examples

POST /v1/api_keys/{id}/roll

Parameters

Request body

Errors

Examples

POST /v1/api_keys/{id}/revoke

Parameters

Request body

Errors

Examples

GET `/v1/api_keys`

POST `/v1/api_keys`

GET `/v1/api_keys/{id}`

POST `/v1/api_keys/{id}/roll`

POST `/v1/api_keys/{id}/revoke`