API Keys

Endpointhttps://api.kontier.eu/v1

Create, rotate and revoke the API keys your integration authenticates with. See Authentication.

List API keys

GET

https://api.kontier.eu/v1

/api-keys

Returns the API keys of the current workspace, revoked ones included, newest first, with limit/cursor paging. The plaintext key is never returned; each key is identified by its key_type and last4. include=created_by names who minted each key as {id, name, email}; its display goes on 2026-11-30.

Required scope: apikey.read (Read API keys).

List API keys › query Parameters

include

string[] · explode: true

Extra data to add to the response: created_by. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. created_by is sent without being asked until 2026-11-30; after that date it is sent only when named here.

Enum values:

created_by

limit

integer · min: 1

Page size (default 50, max 200).

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List API keys › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List API keys › Responses

array | null · required

object · required

GET/api-keys

curl --request GET \
  --url https://api.kontier.eu/v1/api-keys

shell

Example Responses

{
  "data": [
    {
      "access": {
        "permission_count": 0,
        "preset": "FULL_ACCESS"
      },
      "allowed_ips": [
        "string"
      ],
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": {
        "display": "display",
        "email": "email",
        "id": "ba076294-a756-5ce2-b441-74899344e0d5",
        "name": "name"
      },
      "created_by_id": "1e7cbfd8-8768-53f3-a3cc-78c27d64e9d3",
      "expires_at": "2024-08-25T15:00:00Z",
      "id": "27ddd992-6c47-5325-aaa0-e4265347ad0c",
      "key_prefix": "key_prefix",
      "key_type": "sk_test",
      "last4": "last4",
      "last_used_at": "2024-08-25T15:00:00Z",
      "name": "name",
      "replaced_by_id": "c8b6dbdd-a832-5d12-802f-9a49cb743b97",
      "replaces_id": "f7b2f8ba-94c0-5778-bf7f-5ea8abad3e28",
      "scopes": [
        "string"
      ],
      "status": "active",
      "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create an API key

POST

https://api.kontier.eu/v1

/api-keys

Mints a new API key and returns it as the list shows it, plus the plaintext key (sk_live_... or sk_test_...) in key. The plaintext is returned once and never stored: record it now.

Required scope: apikey.manage (Manage API keys).

Create an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Create an API key › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create an API key › Request Body

name

string · minLength: 1 · maxLength: 80 · required

Human-readable label for the key, shown in the dashboard list; at most 80 characters. Leading and trailing whitespace is trimmed. Name it after what uses it, e.g. "Shop backend – order sync".

access_preset

string · enum

A named grant, expanded against the permissions you hold — a key never carries more than its creator: READ_ONLY is every read permission you hold (the least-privilege default), FULL_ACCESS everything you hold. CUSTOM is refused: pass scopes instead. Exactly one of access_preset and scopes is required.

Enum values:

FULL_ACCESS

READ_ONLY

CUSTOM

allowed_ips

array | null

IP addresses or CIDR blocks permitted to present this key. Omit or pass an empty list to leave the key unrestricted.

expires_at

string · date-time

Moment the key stops authenticating; must be in the future. Omit for a non-expiring key.

key_type

string · enum

Key environment: "sk_live" or "sk_test". Omit it: the workspace's mode decides (sandbox workspaces mint sk_test, live workspaces mint sk_live). A value that disagrees with the workspace's mode is refused (400, field code KEY_TYPE_MODE_MISMATCH).

Enum values:

sk_test

sk_live

scopes

array | null

Explicit permissions, e.g. "customer.read"; each must be one you hold. GET /v1/permissions returns the catalog. An empty list is not all-access. Exactly one of access_preset and scopes is required.

Create an API key › Responses

Created

object · required

POST/api-keys

curl --request POST \
  --url https://api.kontier.eu/v1/api-keys \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "access_preset": "FULL_ACCESS",
  "allowed_ips": [
    "string"
  ],
  "expires_at": "2024-08-25T15:00:00Z",
  "key_type": "sk_test",
  "name": "name",
  "scopes": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "access_preset": "FULL_ACCESS",
  "allowed_ips": [
    "string"
  ],
  "expires_at": "2024-08-25T15:00:00Z",
  "key_type": "sk_test",
  "name": "name",
  "scopes": [
    "string"
  ]
}

json

Example Responses

{
  "data": {
    "access": {
      "permission_count": 0,
      "preset": "FULL_ACCESS"
    },
    "allowed_ips": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": {
      "display": "display",
      "email": "email",
      "id": "ba076294-a756-5ce2-b441-74899344e0d5",
      "name": "name"
    },
    "created_by_id": "1e7cbfd8-8768-53f3-a3cc-78c27d64e9d3",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "e295a4fd-dd70-5bb1-926a-98dd2850bb2c",
    "key": "key",
    "key_prefix": "key_prefix",
    "key_type": "sk_test",
    "last4": "last4",
    "last_used_at": "2024-08-25T15:00:00Z",
    "message": "message",
    "name": "name",
    "new_key": "new_key",
    "old_key_expiry": "2024-08-25T15:00:00Z",
    "replaced_by_id": "c8b6dbdd-a832-5d12-802f-9a49cb743b97",
    "replaces_id": "f7b2f8ba-94c0-5778-bf7f-5ea8abad3e28",
    "scopes": [
      "string"
    ],
    "status": "active",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

json

application/json

Get an API key

GET

https://api.kontier.eu/v1

/api-keys/{id}

Returns one API key of the current workspace as the list shows it, revoked or not. The plaintext key is never returned. A key of another workspace is a 404.

Required scope: apikey.read (Read API keys).

Get an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Get an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Get an API key › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an API key › Responses

object · required

GET/api-keys/{id}

curl --request GET \
  --url https://api.kontier.eu/v1/api-keys/:id

shell

Example Responses

{
  "data": {
    "access": {
      "permission_count": 0,
      "preset": "FULL_ACCESS"
    },
    "allowed_ips": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": {
      "display": "display",
      "email": "email",
      "id": "ba076294-a756-5ce2-b441-74899344e0d5",
      "name": "name"
    },
    "created_by_id": "1e7cbfd8-8768-53f3-a3cc-78c27d64e9d3",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "27ddd992-6c47-5325-aaa0-e4265347ad0c",
    "key_prefix": "key_prefix",
    "key_type": "sk_test",
    "last4": "last4",
    "last_used_at": "2024-08-25T15:00:00Z",
    "name": "name",
    "replaced_by_id": "c8b6dbdd-a832-5d12-802f-9a49cb743b97",
    "replaces_id": "f7b2f8ba-94c0-5778-bf7f-5ea8abad3e28",
    "scopes": [
      "string"
    ],
    "status": "active",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

json

application/json

Revoke an API key

POST

https://api.kontier.eu/v1

/api-keys/{id}/revoke

Revokes an API key and returns it with status revoked. Requests presenting the key then fail with 401.

Required scope: apikey.manage (Manage API keys).

Revoke an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Revoke an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Revoke an API key › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Revoke an API key › Responses

object · required

POST/api-keys/{id}/revoke

curl --request POST \
  --url https://api.kontier.eu/v1/api-keys/:id/revoke \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "access": {
      "permission_count": 0,
      "preset": "FULL_ACCESS"
    },
    "allowed_ips": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": {
      "display": "display",
      "email": "email",
      "id": "ba076294-a756-5ce2-b441-74899344e0d5",
      "name": "name"
    },
    "created_by_id": "1e7cbfd8-8768-53f3-a3cc-78c27d64e9d3",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "27ddd992-6c47-5325-aaa0-e4265347ad0c",
    "key_prefix": "key_prefix",
    "key_type": "sk_test",
    "last4": "last4",
    "last_used_at": "2024-08-25T15:00:00Z",
    "name": "name",
    "replaced_by_id": "c8b6dbdd-a832-5d12-802f-9a49cb743b97",
    "replaces_id": "f7b2f8ba-94c0-5778-bf7f-5ea8abad3e28",
    "scopes": [
      "string"
    ],
    "status": "active",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

json

application/json

Rotate an API key

POST

https://api.kontier.eu/v1

/api-keys/{id}/rotate

Rotates one key: mints a new key with exactly that key's name, scopes, IP allow-list and expiry, and puts that key alone on a 24-hour grace expiry. Returns the new key as the list shows it (its replaces_id names the rotated key), plus its plaintext in key, returned once. Every scope the key carries must be held by the caller (403 otherwise), as when minting. A key already expiring within the grace window is a 409.

Required scope: apikey.manage (Manage API keys).

Rotate an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Rotate an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Rotate an API key › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Rotate an API key › Responses

Created

object · required

POST/api-keys/{id}/rotate

curl --request POST \
  --url https://api.kontier.eu/v1/api-keys/:id/rotate \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "access": {
      "permission_count": 0,
      "preset": "FULL_ACCESS"
    },
    "allowed_ips": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": {
      "display": "display",
      "email": "email",
      "id": "ba076294-a756-5ce2-b441-74899344e0d5",
      "name": "name"
    },
    "created_by_id": "1e7cbfd8-8768-53f3-a3cc-78c27d64e9d3",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "e295a4fd-dd70-5bb1-926a-98dd2850bb2c",
    "key": "key",
    "key_prefix": "key_prefix",
    "key_type": "sk_test",
    "last4": "last4",
    "last_used_at": "2024-08-25T15:00:00Z",
    "message": "message",
    "name": "name",
    "new_key": "new_key",
    "old_key_expiry": "2024-08-25T15:00:00Z",
    "replaced_by_id": "c8b6dbdd-a832-5d12-802f-9a49cb743b97",
    "replaces_id": "f7b2f8ba-94c0-5778-bf7f-5ea8abad3e28",
    "scopes": [
      "string"
    ],
    "status": "active",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

json

application/json

Permissions Identity Providers

List API keys

GET

https://api.kontier.eu/v1

/api-keys

Required scope: apikey.read (Read API keys).

List API keys › query Parameters

include

string[] · explode: true

Enum values:

created_by

limit

integer · min: 1

Page size (default 50, max 200).

Example: 50

cursor

string

List API keys › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List API keys › Responses

array | null · required

object · required

Create an API key

POST

https://api.kontier.eu/v1

/api-keys

Mints a new API key and returns it as the list shows it, plus the plaintext key (sk_live_... or sk_test_...) in key. The plaintext is returned once and never stored: record it now.

Required scope: apikey.manage (Manage API keys).

Create an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Create an API key › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create an API key › Request Body

name

string · minLength: 1 · maxLength: 80 · required

Human-readable label for the key, shown in the dashboard list; at most 80 characters. Leading and trailing whitespace is trimmed. Name it after what uses it, e.g. "Shop backend – order sync".

access_preset

string · enum

Enum values:

FULL_ACCESS

READ_ONLY

CUSTOM

allowed_ips

array | null

IP addresses or CIDR blocks permitted to present this key. Omit or pass an empty list to leave the key unrestricted.

expires_at

string · date-time

Moment the key stops authenticating; must be in the future. Omit for a non-expiring key.

key_type

string · enum

Enum values:

sk_test

sk_live

scopes

array | null

Explicit permissions, e.g. "customer.read"; each must be one you hold. GET /v1/permissions returns the catalog. An empty list is not all-access. Exactly one of access_preset and scopes is required.

Create an API key › Responses

Created

object · required

Get an API key

GET

https://api.kontier.eu/v1

/api-keys/{id}

Returns one API key of the current workspace as the list shows it, revoked or not. The plaintext key is never returned. A key of another workspace is a 404.

Required scope: apikey.read (Read API keys).

Get an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Get an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Get an API key › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an API key › Responses

object · required

Revoke an API key

POST

https://api.kontier.eu/v1

/api-keys/{id}/revoke

Revokes an API key and returns it with status revoked. Requests presenting the key then fail with 401.

Required scope: apikey.manage (Manage API keys).

Revoke an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Revoke an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Revoke an API key › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Revoke an API key › Responses

object · required

Rotate an API key

POST

https://api.kontier.eu/v1

/api-keys/{id}/rotate

Required scope: apikey.manage (Manage API keys).

Rotate an API key › path Parameters

id

string · uuid · required

API key ID (UUID)

Rotate an API key › query Parameters

include

string[] · explode: true

Enum values:

created_by

Rotate an API key › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Rotate an API key › Responses

Created

object · required