Skip to main content
POST
Grant a role

Authorizations

Authorization
string
header
required

Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.

Headers

Idempotency-Key
string

A caller-chosen key, 8 to 255 characters, that makes this create safe to retry. The first request to use a key runs normally and its response is stored for 24 hours. A later request with the same key and the same body is not executed again: it returns the stored response, marked with X-Idempotent-Replay: true. The same key with a different body is refused 409 idempotency_error, as is a retry sent while the original is still running. Only successful responses are stored, so a create that failed can simply be retried with the same key.

Required string length: 8 - 255

Body

application/json
principal
object
required
roleId
string
required
Required string length: 1 - 128
scope
object
required
expiresAt
string<date-time>

Response

201 - application/json

Success

id
string
required
principal
object
required
role
object
required
scope
object
required
status
enum<string>
required
Available options:
active,
expired
expiresAt
string<date-time> | null
required
createdAt
string<date-time>
required
Last modified on October 12, 2026