Master Key Management

Master keys authenticate platform-level operations. They use the mk_ prefix and are passed via the X-Master-Key header.

List master keys

GET /v1/platform/master-keys

curl http://localhost:4000/v1/platform/master-keys \
  -H "X-Master-Key: mk_your_key"

Response (200)

{
  "master_keys": [
    {
      "id": "key-uuid",
      "key": "mk_a1b2c3...",
      "name": "production",
      "owner_email": "admin@company.com",
      "active": true,
      "created_at": "2026-03-26T12:00:00.000Z",
      "revoked_at": null
    },
    {
      "id": "key-uuid-2",
      "key": "mk_d4e...",
      "name": "staging",
      "owner_email": null,
      "active": false,
      "created_at": "2026-03-20T12:00:00.000Z",
      "revoked_at": "2026-03-25T12:00:00.000Z"
    }
  ],
  "count": 2
}

Revoked keys show a truncated key value. Active keys show the full value.

Create master key

POST /v1/platform/master-keys

curl -X POST http://localhost:4000/v1/platform/master-keys \
  -H "X-Master-Key: mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "owner_email": "devops@company.com"}'

Response (201)

{
  "id": "key-uuid",
  "key": "mk_new_master_key_value",
  "name": "ci-pipeline",
  "owner_email": "devops@company.com",
  "created_at": "2026-03-26T12:00:00.000Z"
}

Revoke master key

DELETE /v1/platform/master-keys/{id}

Revoke a master key. You cannot revoke the key you are currently using.

curl -X DELETE http://localhost:4000/v1/platform/master-keys/KEY_ID \
  -H "X-Master-Key: mk_your_key"

Response (200)

{
  "revoked": true,
  "id": "key-uuid"
}

Errors

Status	Code	Description
400	`SELF_REVOKE`	Cannot revoke the key you are currently using
404	`NOT_FOUND`	Master key not found

Master Key Management

On this page