Herald
OpenapiApi keys

Create a new API Key

Generates a new API key for the specified realm. The plaintext key is returned only in this response and cannot be retrieved later.

POST
/api/api-keys

Generates a new API key for the specified realm. The plaintext key is returned only in this response and cannot be retrieved later.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

clientAppId*string

Client App to bind this API key to. Required — every API key must be explicitly bound; a key whose bound app is disabled fails auth.

Formatuuid
expiresAt?|

Optional expiration time (ISO 8601 string)

name*string

Human-readable name for the API key (1-100 characters)

roleIds?array<>|

Optional role IDs to assign to this API key after creation (max 20).

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/api-keys" \  -H "Content-Type: application/json" \  -d '{    "clientAppId": "123e4567-e89b-12d3-a456-426614174000",    "name": "Production API Key"  }'
{  "clientAppEnabled": true,  "clientAppId": "d386372c-64d9-49da-bb8b-4b5eda60f56c",  "clientAppName": "string",  "createdAt": "string",  "enabled": true,  "expiresAt": "string",  "id": "string",  "key": "string",  "name": "string",  "realmId": "string",  "roleBindingError": "string"}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}