API key contract preview

Review the proposed inspection and rotation flow.

Proposed key inspection

GEThttps://{your-api-host}/orgs/{org_uuid}/api/key

Illustrates a proposed active-key inspection.

curl -X GET "https://{your-api-host}/orgs/{org_uuid}/api/key" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Illustrative response

{
  "key_id": "key_abc123",
  "name": "Production API Key",
  "created_at": "2025-01-01T00:00:00Z",
  "last_used_at": "2025-01-10T12:00:00Z",
  "scopes": ["instances:read", "instances:write"]
}

Proposed key rotation

POSThttps://{your-api-host}/orgs/{org_uuid}/api/key/rotate

Illustrates a proposed key-rotation request.

warning

Under the proposed contract, rotation would invalidate the old key. Clients would need to adopt the replacement to avoid interruptions.

curl -X POST "https://{your-api-host}/orgs/{org_uuid}/api/key/rotate" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Illustrative response

{
  "key": "legba_new_api_key_xyz789",
  "key_id": "key_xyz789",
  "created_at": "2025-01-10T12:30:00Z"
}