Creating API Keys

Production - POST /api/v1/api-keys

API keys are created with a name, scopes, and optional configuration for expiration, IP whitelisting, and rate limiting. The full key value is returned only at creation time.

6.6.1Create API Key

curl -X POST http://localhost:8081/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "name": "Production Data Pipeline",
    "description": "Key for automated data pipeline service",
    "scopes": ["queries:execute", "pipelines:execute", "catalog:read"],
    "keyType": "service",
    "testMode": false,
    "expirationDays": 365,
    "ipWhitelist": ["10.0.0.0/8"],
    "rateLimit": 1000
  }'

Request Schema

Field	Type	Required	Validation	Description
`name`	String	Yes	`@NotBlank`, max 255	Human-readable name
`description`	String	No	Max 1000	Purpose of the key
`scopes`	Set<String>	Yes	`@NotEmpty`	Permission scopes
`keyType`	String	No		`user`, `service`, or `integration`
`testMode`	boolean	No		Creates a test key (prefix: `mk_test_`)
`expirationDays`	Integer	No		Days until expiration (null = never)
`ipWhitelist`	Set<String>	No		Allowed IP addresses/CIDR blocks
`rateLimit`	Integer	No		Max requests per minute (0 = unlimited)

Response (201 Created)

{
  "keyId": 15,
  "fullKey": "mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "keyPrefix": "mk_live_",
  "name": "Production Data Pipeline",
  "scopes": ["queries:execute", "pipelines:execute", "catalog:read"],
  "expiresAt": "2027-02-12T10:00:00Z",
  "createdAt": "2026-02-12T10:00:00Z"
}

The fullKey is only shown once. Store it securely.

6.6.2List API Keys

# List user's keys
curl -X GET "http://localhost:8081/api/v1/api-keys?activeOnly=true" \
  -H "Authorization: Bearer <access-token>"
 
# List tenant keys (admin)
curl -X GET http://localhost:8081/api/v1/api-keys/tenant \
  -H "Authorization: Bearer <admin-token>"

Validate API Key

curl -X POST http://localhost:8081/api/v1/api-keys/validate \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" }'

Revoke API Key

curl -X DELETE http://localhost:8081/api/v1/api-keys/15 \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "No longer needed" }'

Error Codes

Code	HTTP Status	Description
`API_KEY_NOT_FOUND`	404	Key not found
`API_KEY_LIMIT_EXCEEDED`	429	Maximum key limit reached
`DUPLICATE_KEY_NAME`	409	Key name already exists
`INVALID_SCOPE`	400	One or more scopes are not valid

Overview Key Rotation