API keys

An API key lets scripts and tools call the API as you, with your role in each workspace. Send it as Authorization: Bearer ctk_… or X-API-Key: ctk_…. Its secret is shown once, when the key is created.

The ApiKey object

An API key that acts as you. The API shows only its first and last characters, never the full secret.

Attributes

idstringRequired

Unique ID of the API key.

namestringRequired

The name you gave the key, such as CI deploys.

tokenPrefixstringRequired

The secret's first 8 characters, such as ctk_9fQx, to recognize the key.

lastFourstringRequired

The secret's last 4 characters.

createdAtstringRequired

When the key was created, as an ISO 8601 timestamp.

lastUsedAtnullable stringRequired

When the key last authenticated a request, as an ISO 8601 timestamp; null if never.

The ApiKey object

{  "id": "Ak8TqW3nVr5L",  "name": "CI deploys",  "tokenPrefix": "ctk_9fQx",  "lastFour": "rVwA",  "createdAt": "2026-10-01T16:20:00.000Z",  "lastUsedAt": "2026-10-14T09:05:12.000Z"}

List API keys

GET/v1/api-keys

Returns your API keys that are not revoked, newest first. Account API keys cannot list keys.

Returns

Returns an array of ApiKey objects. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/api-keys

1curl https://api.qa.clankership.net/v1/api-keys \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

[  {    "id": "Ak8TqW3nVr5L",    "name": "CI deploys",    "tokenPrefix": "ctk_9fQx",    "lastFour": "rVwA",    "createdAt": "2026-10-01T16:20:00.000Z",    "lastUsedAt": "2026-10-14T09:05:12.000Z"  }]

Create an API key

POST/v1/api-keys

Creates an API key that acts as you and returns its secret, which is shown only this once. You can have up to 20 active keys. Account API keys cannot create keys.

Body parameters

namestringRequired

A name that says where the key is used, 1 to 80 characters.

Returns

Returns an object with these fields. Status 200.

An API key you just created, with its secret.

idstringRequired

Unique ID of the API key.

namestringRequired

The name you gave the key, such as CI deploys.

tokenPrefixstringRequired

The secret's first 8 characters, such as ctk_9fQx, to recognize the key.

lastFourstringRequired

The secret's last 4 characters.

secretstringRequired

The full key, starting with ctk_. Store it now: the API never returns it again.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/api-keys

1curl -X POST https://api.qa.clankership.net/v1/api-keys \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "CI deploys"6  }'

Response200

{  "id": "Ak8TqW3nVr5L",  "name": "CI deploys",  "tokenPrefix": "ctk_9fQx",  "lastFour": "rVwA",  "secret": "ctk_9fQxR2mT7vLp4WnK8sDj3HcB6yZa1EuG5oNi0qXrVwA"}

Revoke an API key

POST/v1/api-keys/{apiKeyId}/revoke

Revokes one of your API keys, so requests with it fail with Unauthorized from then on. Fails with NotFound when the key is not yours or is already revoked.

Path parameters

apiKeyIdstringRequired

The API key's ID, such as Ak8TqW3nVr5L.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/api-keys/{apiKeyId}/revoke

1curl -X POST https://api.qa.clankership.net/v1/api-keys/{apiKeyId}/revoke \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "ok": true}

NextWorkspaces