API Keys

API keys are bearer tokens for programmatic access to a workspace. Use them for servers, CLIs, automations, and other non-browser clients. Manage them with client.apiKeys.

Quick Links

Action	Description
`apiKeys.list()`	List workspace API keys.
`apiKeys.create()`	Create an API key.
`apiKeys.get()`	Read API key metadata.
`apiKeys.update()`	Update an API key's name or scopes.
`apiKeys.rotate()`	Rotate an API key secret.
`apiKeys.revoke()`	Revoke an API key.

Use An API Key

Pass the key to createSkopikClient({ apiKey }) and the SDK sends it as a bearer token on every request. Raw HTTP callers send it themselves:

curl "$SKOPIK_API_BASE/agents" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Store API keys like passwords. The secret is returned only when the key is created or rotated.

Scopes

Scopes limit what a key can do.

Scope family	Enables
`org:admin`	Workspace administration, members, invites, and API keys.
`agents:*`	Agent and team reads/writes.
`agents:run`	Dispatching agent work.
`tasks:*`	Projects, tasks, and operations.
`messages:*`	Conversations and messages.
`files:*`	Uploading, reading, indexing, and summarizing files.
`templates:` and `skills:`	Reusable templates and skills.
`usage:read`	Workspace usage summaries.

Reference

`apiKeys.list()`

List API keys for the current workspace.

const { data: keys } = await client.apiKeys.list()

keys = client.api_keys.list().data

curl "$SKOPIK_API_BASE/api-keys" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns ListResponse<ApiKey> — { data: ApiKey[] }. See ApiKey.

`apiKeys.create(input)`

Create a workspace API key. The response is the only time the key's secret is available — store it immediately. Grant only the scopes the consumer needs.

const { apiKey } = await client.apiKeys.create({
	name: 'CI deploy key',
	scopes: ['agents:read', 'tasks:write', 'agents:run'],
})

api_key = client.api_keys.create(
    name="CI deploy key",
    scopes=["agents:read", "tasks:write", "agents:run"],
).api_key

curl "$SKOPIK_API_BASE/api-keys" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI deploy key",
    "scopes": ["agents:read", "tasks:write", "agents:run"]
  }'

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Human-readable key name.
`scopes`	string[]	No	Granted scopes. Defaults to `[]`.
`expiresAt`	string	No	Optional ISO expiration timestamp.
`metadata`	object	No	Customer metadata.

Returns { apiKey: ApiKey } — includes secret on this call only. See ApiKey.

`apiKeys.get(keyId)`

Read API key metadata. Reads never return the secret.

const { apiKey } = await client.apiKeys.get(keyId)

api_key = client.api_keys.get(key_id).api_key

curl "$SKOPIK_API_BASE/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { apiKey: ApiKey } — see ApiKey.

`apiKeys.update(keyId, input)`

Update API key metadata or scopes.

const { apiKey } = await client.apiKeys.update(keyId, {
	scopes: ['agents:read', 'tasks:write'],
})

api_key = client.api_keys.update(
    key_id,
    scopes=["agents:read", "tasks:write"],
).api_key

curl "$SKOPIK_API_BASE/api-keys/$KEY_ID" \
  -X PATCH \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["agents:read", "tasks:write"]
  }'

Parameters

Field	Type	Required	Notes
`name`	string	No	New display name.
`scopes`	string[]	No	Replacement scope list.
`metadata`	object	No	Replacement metadata.

Returns { apiKey: ApiKey } — see ApiKey.

`apiKeys.rotate(keyId)`

Rotate an API key secret. The old secret stops authenticating and the new secret is returned once — update every consumer before rotating a key that is in active use.

const { apiKey } = await client.apiKeys.rotate(keyId)

api_key = client.api_keys.rotate(key_id).api_key

curl "$SKOPIK_API_BASE/api-keys/$KEY_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { apiKey: ApiKey } — includes the new secret on this call only. See ApiKey.

`apiKeys.revoke(keyId)`

Revoke an API key. Revoked keys stop authenticating immediately.

await client.apiKeys.revoke(keyId)

client.api_keys.revoke(key_id)

curl "$SKOPIK_API_BASE/api-keys/$KEY_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns nothing — resolves when the API confirms revocation (HTTP 204).

Types

`ApiKey`

Field	Type	Notes
`keyId`	string	API key id.
`name`	string	Display name.
`owner`	string	User or caller that owns the key.
`orgId`	string	Workspace id.
`hashedKeyPrefix`	string	Prefix used to identify the key without exposing the secret.
`scopes`	string[]	Granted scopes.
`createdBy`	string	Creator id.
`expiresAt`	string \| null	Optional expiration timestamp.
`lastUsedAt`	string	Last use timestamp.
`revokedAt`	string \| null	Revocation timestamp, if revoked.
`secret`	string	Present only in `create()` and `rotate()` responses. Store it like a password.
`metadata`	object	Customer metadata.
`createdAt`	string	ISO timestamp.
`updatedAt`	string	ISO timestamp.