Skip to content
Governance Platform

Create API key

POST
/api/v1/api-keys
 
curl --request POST \
  --url https://localhost:8080/api/v1/api-keys \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "allowedIps": [ "example" ], "description": "example", "expiresAt": "2026-12-31T23:59:59Z", "name": "example", "organizationId": 1, "projectId": 1, "scopes": [ "example" ] }'

Create a new API key for service-to-service authentication. JWT/session only — API keys cannot manage API keys. Scopes must be grantable by the creator; "" is organization-owner only, and "" or empty is rejected when projectId binds the key. expiresAt is required, in the future, within 365 days

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

API key configuration

Media type application/json
object
allowedIps

Enforced on every request when set

Array<string>
description
required
string
expiresAt
required

Future, within MaxAPIKeyLifetime

string format: date-time
Example 
2026-12-31T23:59:59Z
name
required
string
>= 1 characters <= 255 characters
organizationId

Scopes the key to an organization

integer
projectId

Scopes the key to a project

integer
scopes

”*” (full access) must be alone

Array<string>

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Created API key (key shown only once)

Media type application/json

A newly created API key together with its plaintext secret, which is shown only in this response

object
apiKey

An API key for service-to-service authentication; the secret itself is never returned here

object
allowedIps
Array<string>
createdAt
string format: date-time
createdBy
string
description
string
expiresAt
string format: date-time
id
string
keyId
string
lastUsedAt
string format: date-time
name
string
organizationId
integer
projectId
integer
revocationReason

Set via the revoke endpoint

string
revokedAt
string format: date-time
revokedBy
string
scopes
Array<string>
status
string
Allowed values: active expired revoked
usageCount
integer
userId

Resolved from the caller

string
plainKey

Only returned once during creation

string
Example 
{
  "apiKey": {
    "status": "active"
  }
}

400

Section titled “400 ”

Bad request - Invalid body, name, description, expiry, or scopes

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

401

Section titled “401 ”

Unauthorized - Authentication required

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

403

Section titled “403 ”

Forbidden - API keys cannot manage API keys

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

500

Section titled “500 ”

Internal server error

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}