External Auth Claim Mappings

Create, list, get, supersede, and preview-resolve external auth claim mappings that link customer-attested claims to internal roles.

External auth claim mappings define the workspace allowlist that connects customer-attested authorization claims to internal external roles. Each active mapping links exactly one claim tuple - a (namespace, key, value) triple - to one external role. Matching is exact, case-sensitive tuple equality only.

Mappings are immutable. There is no update verb. To change a mapping, supersede the existing one (which marks it as superseded) and create a new active mapping. This preserves the full authorization history for audit.

Base Path

/v1/{workspace_id}/external-auth-claim-mappings

Endpoints

Method	Path	Operation	Description
GET	/	list-external-auth-claim-mappings	List mappings with optional status filter and pagination
POST	/	create-external-auth-claim-mapping	Create a new active mapping
GET	/{mapping_id}	get-external-auth-claim-mapping	Get a single mapping by ID
POST	/{mapping_id}/supersede	supersede-external-auth-claim-mapping	Supersede an active mapping (mark as superseded)
POST	/resolve-preview	resolve-preview-external-auth-claim-mappings	Dry-run the claim resolver against current workspace config

Permissions

• Create and supersede require Workspace.update (admin or owner).
• List, get, and resolve-preview require Workspace.view.

Claim Tuple Format

Each claim mapping references a claim tuple with three fields:

Field	Type	Constraints
claim_namespace	string	Lowercase identifier, 1-64 characters. Pattern: ^[a-z][a-z0-9_.:-]{0,63}$
claim_key	string	Lowercase identifier, 1-64 characters. Same pattern as namespace
external_value	string	1-256 characters, preserved exactly as provided (no lowercasing or aliasing)

The same identifier pattern applies to claim atoms passed during session creation and to mapping definitions.

Create a Mapping

POST /v1/{workspace_id}/external-auth-claim-mappings

Request Body

Field	Type	Required	Description
claim_namespace	string	Yes	Claim namespace
claim_key	string	Yes	Claim key
external_value	string	Yes	The customer's asserted value
external_role_id	uuid	Yes	The external role this claim maps to (must exist in this workspace)

Response

Returns the created mapping item with status 201 Created.

Errors

Status	Condition
409	An active mapping for this claim tuple already exists
422	external_role_id does not reference an external role in this workspace

List Mappings

GET /v1/{workspace_id}/external-auth-claim-mappings

Query Parameters

Parameter	Type	Default	Description
status	string	(all)	Filter by active or superseded
limit	integer	50	Page size (1-200)
continuation_token	string	(none)	Pagination token from a previous response
sort_by	string	-created_at	Sort field with direction prefix (+created_at or -created_at)

Response

Field	Type	Description
items	array	List of mapping items
has_more	boolean	Whether more results are available
continuation_token	string or null	Token for the next page, if has_more is true

Get a Mapping

GET /v1/{workspace_id}/external-auth-claim-mappings/{mapping_id}

Returns a single mapping item. Returns 404 if not found.

Supersede a Mapping

POST /v1/{workspace_id}/external-auth-claim-mappings/{mapping_id}/supersede

Marks an active mapping as superseded. Returns the mapping item in its final state. Returns 404 if no active mapping exists for that ID.

Superseding a mapping invalidates cached authorization resolutions across the workspace. The next external-user turn re-resolves against the updated configuration.

Resolve Preview

POST /v1/{workspace_id}/external-auth-claim-mappings/resolve-preview

Dry-run the same resolver that runs on every external-user turn. This is read-only and never creates sessions, roles, mappings, or grants.

Request Body

Field	Type	Required	Description
auth_claims	array	No	List of claim atoms (max 32), each with namespace, key, and value

Response

Field	Type	Description
roles	array	Mapped internal roles (each with id and name)
grants	array	Effective grants from the mapped roles (each with resource_type, resource_key, and access)
unmapped_claim_count	integer	Number of input claim atoms with no active mapping

Mapping Item Shape

Field	Type	Description
id	uuid	Mapping ID
claim_namespace	string	Claim namespace
claim_key	string	Claim key
external_value	string	The customer's asserted value
external_role_id	uuid	The external role this claim maps to
status	string	active or superseded
changed_by	uuid or null	Credential that created or superseded this mapping
created_at	datetime	When the mapping was created

Auth Claims on Session Creation

The external-user session token grant (grant_type=external_user_session) accepts an optional auth_claims form field containing a JSON-serialized array of claim atoms. Each atom has namespace, key, and value fields. Claims are validated, deduplicated, sorted, and stored immutably on the session.

• Omitting auth_claims or passing an empty string produces an empty claim set (backward compatible).
• Including auth_claims on any other grant type returns a 400 invalid_request error.
• A maximum of 32 claims per session is enforced.
• The serialized payload must not exceed 4096 bytes.

See Sessions for the full external-user session token grant documentation.