Create an organization role
POST /fapi/v1/organizations/{org_id}/roles · called from the environment's sign-in host
Creates a role in the organization, without permissions; add them with Set role permissions. An organization holds at most 50 roles. Requires the authenticated user's __Host-idp_session cookie; if the cookie is missing, expired, or revoked, returns 401 unauthenticated. A first-party app on another origin can instead send its front API access token (Authorization: DPoP <token> with a DPoP proof; see Front API access token). The user must be an active member of the organization with the idp_roles:manage permission. A user who is not a member gets 404 not_found, so the organization's existence is not disclosed; a member without the permission gets 403 insufficient_permissions. Organization roles must be enabled for the environment and included in its plan.
Request
Headers:
| Header | Required | Description |
|---|---|---|
Idp-Client |
yes | SDK identifier. |
Origin |
yes | Must be exactly https://<sign-in host>. |
Content-Type |
yes | application/json. |
org_id: the organization identifier (org_…).
Body:
| Field | Required | Description |
|---|---|---|
key |
yes | Role key; unique in the organization and among environment roles; cannot be changed later. |
name |
yes | Display name. |
description |
no | Description. |
Response
201 Created with Location and ETag headers; the body is the role (see Get an organization role).
Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthenticated |
No valid session cookie. |
| 403 | origin_not_allowed |
Origin is missing or wrong. |
| 403 | insufficient_permissions |
The user lacks idp_roles:manage in the organization. |
| 403 | plan_feature_unavailable |
The environment's plan does not include organization roles (feature, required_plan). |
| 403 | org_custom_roles_disabled |
Organization roles are turned off for the environment. |
| 404 | not_found |
No such organization or role for this user (an unknown, malformed or foreign identifier answers the same). |
| 409 | role_key_conflict |
The key is already used in the organization or by an environment role. |
| 409 | role_limit_reached |
The organization already has 50 roles. |
| 409 | organization_pending_deletion |
The organization is scheduled for deletion. |
| 422 | validation_failed |
A field is missing or invalid; errors[] names it. |
| 503 | service_unavailable |
Temporarily unavailable; retry after Retry-After. |
Example
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"key":"auditor","name":"Auditor"}'