Management keys

Management keys sign management API calls. Only a key of role admin manages them. A new or rotated key's secret is in the answer once, and never again.

All paths are under https://api.mubit.ai, with a management key in Authorization: Bearer. Management API covers keys, roles, pagination, retries and errors. The samples read the key from MUBIT_MANAGEMENT_KEY.

List management keys

GET /api/v1/management-keys

Lists the organization's management keys, newest first, up to limit. The secrets are never returned.

Role: admin.

curl "https://api.mubit.ai/api/v1/management-keys" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY"

Response 200: List of management keys

Each item of data:

{
  "data": [
    {
      "id": "mkey_012345",
      "name": "CI Runner Key",
      "role": "member",
      "project": "prj_ci",
      "status": "active",
      "created_at": "2026-10-10T00:00:00Z",
      "last_used_at": "2026-10-25T18:22:00Z"
    }
  ],
  "next_cursor": null
}

Create management key

POST /api/v1/management-keys

Creates a management key. The answer holds the key's secret in key, once: store it then. The role can't be higher than the role of the key that creates it (403 role_ceiling). With project, the key reaches only that project. With expires_at (an RFC 3339 time in the future), the key stops working then.

Role: admin.

curl -X POST "https://api.mubit.ai/api/v1/management-keys" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Deployment Agent","role":"admin","project":null}'

Response 201: Management key created

{
  "id": "mkey_987654",
  "name": "Deployment Agent",
  "key": "mwm_inst_987654_secrettoken0123456789",
  "role": "admin",
  "project": null,
  "status": "active",
  "created_at": "2026-10-26T12:00:00Z"
}

Rotate management key

POST /api/v1/management-keys/{key_id}/rotate

Gives a management key a new secret, in key, once. The old secret stops working within a minute. A key can rotate itself and the keys made with it, never a key of a higher role (403 role_ceiling) or another key (403 forbidden). A revoked key can't be rotated (409 state_conflict).

Role: admin.

curl -X POST "https://api.mubit.ai/api/v1/management-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Response 200: Rotated management key

{
  "id": "mkey_987654",
  "name": "Deployment Agent",
  "key": "mwm_inst_987654_newsecrettoken9876543",
  "role": "admin",
  "project": null,
  "status": "active",
  "created_at": "2026-10-26T12:00:00Z"
}

Revoke management key

DELETE /api/v1/management-keys/{key_id}

Revokes a management key. It stops working within a minute, and can't be used again.

Role: admin.

curl -X DELETE "https://api.mubit.ai/api/v1/management-keys/$KEY_ID" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY"

Response 200: Management key revoked

{
  "id": "mkey_987654",
  "status": "revoked"
}