OIDC role mapping

Control which role users signing in through OIDC receive, based on the group or role claim values your identity provider sends. Claim values map to one of three roles: admin (full access), builder (manages agents and documents), or member (standard access).

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

Every OIDC role-mapping endpoint is admin only.

The mapping object

OidcGroupRoleMapping is returned by all three endpoints.

Field	Type	Description
roleGroups	object	Claim values per role: `admin`, `builder`, and `member`, each an array of group/role claim values.
updatedAt	string	When the mapping was last changed (nullable).

Get mapping

GET /oidc/group-role-mapping

Returns the current mapping of OIDC group/role claim values to user roles.

curl 'https://{your-deployment-host}/api/v2/oidc/group-role-mapping' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Replace mapping

PUT /oidc/group-role-mapping

Replaces the entire mapping with the one in the body. Empty and duplicate group values are dropped.

Body

Field	Type	Required	Description
roleGroups	object	Yes	Arrays of claim values for `admin`, `builder`, and `member`.

curl -X PUT 'https://{your-deployment-host}/api/v2/oidc/group-role-mapping' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "roleGroups": {
      "admin": ["platform-admins"],
      "builder": ["agent-builders"],
      "member": ["everyone"]
    }
  }'

Returns the updated OidcGroupRoleMapping.

Clear mapping

DELETE /oidc/group-role-mapping

Clears the mapping; new OIDC users then default to the member role. Returns 200 OK with the (now empty) mapping.

curl -X DELETE 'https://{your-deployment-host}/api/v2/oidc/group-role-mapping' \
  -H 'Authorization: Bearer YOUR_API_KEY'

API keys Audit log