Keyring
ReferenceControl-plane API

Secret keys

The `krsk_` credentials your own backend uses against this control plane.

Generated from packages/api/src/resources/secret-keys.controller.ts by packages/docs/tools/generate-reference.mjs. Every example is a real exchange recorded against the control plane by packages/api/src/testing/reference-examples.spec.ts, with ids from that run. Credentials in the formats this product issues (kr_, krsk_, krses_, JWTs) and values under credential-named fields (password, *_secret, *_token, *_key, lookup_hash) are elided at record time; the recorded file and every page of this site are swept for credential shapes (kr_, krsk_, krses_, JWTs, URLs carrying a password, password fields) before either is accepted. Do not edit by hand: src/reference.spec.ts regenerates it and fails on a difference.

The vendor plane (report section 7.1). These are the credentials the customer's own backend holds; they live in their own table so that a control-plane credential can never be picked up by the snapshot query that feeds a customer's SDK cache.

POST /v1/secret_keys

Answers 201 on success.

Authentication.

  • A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Body. Validated by this schema, from the control plane's own source:

const CreateSecretKey = z.object({
  env: Env,
  name: Name.optional(),
  meta: Meta.optional(),
  expires_at: Timestamp.optional(),
});

Example.

Request
curl https://api.keyringdev.com/v1/secret_keys \
  -X POST \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "env": "test",
    "name": "CI runner"
  }'
Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "object": "secret_key",
  "id": "01a0fac2-a575-7c34-9de9-5cda00824b17",
  "env": "test",
  "display_prefix": "krsk_test_X4UOq6",
  "name": "CI runner",
  "meta": {},
  "expires_at": null,
  "revoked_at": null,
  "revoked_reason": null,
  "quarantined_at": null,
  "quarantine_reason": null,
  "rotated_from": null,
  "created_at": "2026-10-02T03:57:35.476Z",
  "last_used_at": null,
  "key": "krsk_test_X4UOq6…",
  "key_shown_once": true
}

GET /v1/secret_keys

Filtered exactly as GET /v1/keys is. A listing of every live credential's display prefix, name and rotation history is the production key namespace, which is the thing a test credential is defined not to reach.

Answers 200 on success.

Authentication.

  • A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Example.

Request
curl https://api.keyringdev.com/v1/secret_keys \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY"
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "list",
  "data": [
    {
      "object": "secret_key",
      "id": "01a0fac2-a575-7c34-9de9-5cda00824b17",
      "env": "test",
      "display_prefix": "krsk_test_X4UOq6",
      "name": "CI runner",
      "meta": {},
      "expires_at": null,
      "revoked_at": null,
      "revoked_reason": null,
      "quarantined_at": null,
      "quarantine_reason": null,
      "rotated_from": null,
      "created_at": "2026-10-02T03:57:35.476Z",
      "last_used_at": null
    },
    {
      "object": "secret_key",
      "id": "01a0fac2-a370-7f7c-9ce3-e89fd96c0d68",
      "env": "live",
      "display_prefix": "krsk_live_yOsAPB",
      "name": "Bootstrap secret key",
      "meta": {},
      "expires_at": null,
      "revoked_at": null,
      "revoked_reason": null,
      "quarantined_at": null,
      "quarantine_reason": null,
      "rotated_from": null,
      "created_at": "2026-10-02T03:57:34.951Z",
      "last_used_at": "2026-10-02T03:57:34.988Z"
    }
  ]
}

GET /v1/secret_keys/:id

Answers 200 on success.

Authentication.

  • A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Path parameters. id.

Example.

Request
curl https://api.keyringdev.com/v1/secret_keys/01a0fac2-a575-7c34-9de9-5cda00824b17 \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY"
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "secret_key",
  "id": "01a0fac2-a575-7c34-9de9-5cda00824b17",
  "env": "test",
  "display_prefix": "krsk_test_X4UOq6",
  "name": "CI runner",
  "meta": {},
  "expires_at": null,
  "revoked_at": null,
  "revoked_reason": null,
  "quarantined_at": null,
  "quarantine_reason": null,
  "rotated_from": null,
  "created_at": "2026-10-02T03:57:35.476Z",
  "last_used_at": null
}

POST /v1/secret_keys/:id/rotate

Answers 200 on success.

Authentication.

  • A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Path parameters. id.

Body. Validated by this schema, from the control plane's own source:

const RotateSecretKey = z.object({
  overlap_hours: z.number().min(0).max(168).default(24),
});

Example.

Request
curl https://api.keyringdev.com/v1/secret_keys/01a0fac2-a575-7c34-9de9-5cda00824b17/rotate \
  -X POST \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overlap_hours": 1
  }'
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "secret_key",
  "id": "01a0fac2-a582-7267-bcc2-cc104dee3264",
  "env": "test",
  "display_prefix": "krsk_test_W9N2fJ",
  "name": "CI runner",
  "meta": {},
  "expires_at": null,
  "revoked_at": null,
  "revoked_reason": null,
  "quarantined_at": null,
  "quarantine_reason": null,
  "rotated_from": "01a0fac2-a575-7c34-9de9-5cda00824b17",
  "created_at": "2026-10-02T03:57:35.488Z",
  "last_used_at": null,
  "key": "krsk_test_W9N2fJ…",
  "key_shown_once": true,
  "previous_key": {
    "object": "secret_key",
    "id": "01a0fac2-a575-7c34-9de9-5cda00824b17",
    "env": "test",
    "display_prefix": "krsk_test_X4UOq6",
    "name": "CI runner",
    "meta": {},
    "expires_at": "2026-10-02T04:57:35.488Z",
    "revoked_at": null,
    "revoked_reason": null,
    "quarantined_at": null,
    "quarantine_reason": null,
    "rotated_from": null,
    "created_at": "2026-10-02T03:57:35.476Z",
    "last_used_at": null
  }
}

POST /v1/secret_keys/:id/revoke

Answers 200 on success.

Authentication.

  • A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Path parameters. id.

Body. Validated by this schema, from the control plane's own source:

const RevokeSecretKey = z.object({
  reason: z.string().min(1).max(500).optional(),
});

Example.

Request
curl https://api.keyringdev.com/v1/secret_keys/01a0fac2-a582-7267-bcc2-cc104dee3264/revoke \
  -X POST \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Runner decommissioned"
  }'
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "secret_key",
  "id": "01a0fac2-a582-7267-bcc2-cc104dee3264",
  "env": "test",
  "display_prefix": "krsk_test_W9N2fJ",
  "name": "CI runner",
  "meta": {},
  "expires_at": null,
  "revoked_at": "2026-10-02T03:57:35.496Z",
  "revoked_reason": "Runner decommissioned",
  "quarantined_at": null,
  "quarantine_reason": null,
  "rotated_from": "01a0fac2-a575-7c34-9de9-5cda00824b17",
  "created_at": "2026-10-02T03:57:35.488Z",
  "last_used_at": null
}

Shared validators

Defined once in packages/api/src/validation.ts and used by the schemas above.

const Env = z.enum(['live', 'test']);
const Meta = z.record(z.string(), z.unknown());
const Name = z.string().min(1).max(200);
const Timestamp = z.iso.datetime({ offset: true });

API keys

Mint, list, update, rotate and revoke the keys your customers present.

Usage

Per-key sparklines, per-tenant counts and the billable-tenant figure.

On this page

POST /v1/secret_keysGET /v1/secret_keysGET /v1/secret_keys/:idPOST /v1/secret_keys/:id/rotatePOST /v1/secret_keys/:id/revokeShared validators