API keys

Credentials for agents, CI, and integrations. A user key acts as the person who owns it; a service key is a machine identity. Secrets are shown once at creation — thereafter only a last-4 hint is returned.

Related guides: Authentication

Attributes

idstringrequired
objectstringrequired
namestringrequired
prefixstringrequired
last4stringrequired
modestringrequired
Possible values: live, test
scopesarray of stringrequired
kindstringrequired
A user key acts as a person; a service key is a machine identity.
Possible values: user, service
acts_asstring | nullrequired
The user a user key acts as (null for a service key).
created_bystring | nullrequired
Who minted the key.
last_used_attimestamprequired
revoked_attimestamprequired
created_attimestamprequired

Endpoints

GET/v1/api_keys
POST/v1/api_keys
DELETE/v1/api_keys/{id}

The ApiKey object

{
  "id": "key_8KxQ2v…",
  "object": "api_key",
  "name": "CI deploy key",
  "prefix": "rza_sk_live_8KxQ2v",
  "last4": "aB3z",
  "mode": "live",
  "scopes": [],
  "kind": "user",
  "acts_as": "usr_1a2b…",
  "created_by": "usr_1a2b…",
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}

List API keys

GET/v1/api_keys

Lists the active org's API keys (newest first). Secrets are never returned — only `prefix` and `last4` for identification.

Requires an API key (bearer), scoped to the active org.

Returns

200The org's API keys.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza keys list

GET /v1/api_keys

curl https://api.renza.io/v1/api_keys \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const page = await renza.apiKeys.list();

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "key_8KxQ2v…",
      "object": "api_key",
      "name": "CI deploy key",
      "prefix": "rza_sk_live_8KxQ2v",
      "last4": "aB3z",
      "mode": "live",
      "scopes": [],
      "kind": "user",
      "acts_as": "usr_1a2b…",
      "created_by": "usr_1a2b…",
      "last_used_at": null,
      "revoked_at": null,
      "created_at": "2026-06-19T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create an API key

POST/v1/api_keys

Mints a livemode secret key for the active org. The full `secret` is returned exactly once in this response and cannot be retrieved later — store it now.

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Body parameters

namestringrequiredmax 120 chars
scopesarray of stringoptional
servicebooleanoptional
Mint a SERVICE key (a machine identity, no acting user). Default is a USER key that acts as the caller — its actions are authored as you (09 §3).
metadataobjectoptional
Arbitrary key/value map; merge-on-write (§6).

Returns

201The created key, including its one-time secret.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza keys create "CI deploy key"

POST /v1/api_keys

curl https://api.renza.io/v1/api_keys \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CI deploy key",
  "scopes": [],
  "service": false
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const key = await renza.apiKeys.create({
  name: "CI deploy key",
  scopes: [],
  service: false,
});

Response 201

{
  "id": "key_8KxQ2v…",
  "object": "api_key",
  "name": "CI deploy key",
  "prefix": "rza_sk_live_8KxQ2v",
  "last4": "aB3z",
  "mode": "live",
  "scopes": [],
  "kind": "user",
  "acts_as": "usr_1a2b…",
  "created_by": "usr_1a2b…",
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}

Revoke an API key

DELETE/v1/api_keys/{id}

Permanently revokes a key. Already-revoked or unknown keys return 404.

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Path parameters

idstringrequired

Returns

200The revoked key.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza keys revoke key_8KxQ2v…

DELETE /v1/api_keys/{id}

curl https://api.renza.io/v1/api_keys/key_8KxQ2v… \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X DELETE

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const key = await renza.apiKeys.revoke("key_8KxQ2v…");

Response 200

{
  "id": "key_8KxQ2v…",
  "object": "api_key",
  "name": "CI deploy key",
  "prefix": "rza_sk_live_8KxQ2v",
  "last4": "aB3z",
  "mode": "live",
  "scopes": [],
  "kind": "user",
  "acts_as": "usr_1a2b…",
  "created_by": "usr_1a2b…",
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}