Federation

Federation lets you map external identity providers (IdPs) to Allternit workspaces and roles. It supports OIDC-compliant issuers and claim-based rules for just-in-time provisioning.

Base URL

/api/v1/admin/federation

Issuer endpoints

Method	Path	Description
`POST`	`/api/v1/admin/federation/issuers`	Add an issuer
`GET`	`/api/v1/admin/federation/issuers`	List issuers
`GET`	`/api/v1/admin/federation/issuers/:id`	Get an issuer
`PUT`	`/api/v1/admin/federation/issuers/:id`	Update an issuer
`DELETE`	`/api/v1/admin/federation/issuers/:id`	Delete an issuer

Rule endpoints

Method	Path	Description
`POST`	`/api/v1/admin/federation/rules`	Add a mapping rule
`GET`	`/api/v1/admin/federation/rules`	List mapping rules
`GET`	`/api/v1/admin/federation/rules/:id`	Get a mapping rule
`PUT`	`/api/v1/admin/federation/rules/:id`	Update a mapping rule
`DELETE`	`/api/v1/admin/federation/rules/:id`	Delete a mapping rule

Add an issuer

curl -X POST https://api.allternit.com/api/v1/admin/federation/issuers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_url": "https://accounts.example.com",
    "enabled": true
  }'

Request body

{
  "issuer_url": "https://accounts.example.com",
  "enabled": true
}

Response

{
  "id": "iss_01hqx8x7x7x7x7x7x7x7x7x",
  "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "issuer_url": "https://accounts.example.com",
  "enabled": true,
  "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
  "created_at": "2026-08-13T18:00:00Z",
  "updated_at": "2026-08-13T18:00:00Z"
}

Issuer URLs must use https:// and be ≤ 512 characters.

Add a mapping rule

curl -X POST https://api.allternit.com/api/v1/admin/federation/rules \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "iss_01hqx8x7x7x7x7x7x7x7x7x",
    "claim_name": "groups",
    "claim_value": "engineering",
    "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
    "role": "admin"
  }'

Request body

{
  "issuer_id": "iss_01hqx8x7x7x7x7x7x7x7x7x",
  "claim_name": "groups",
  "claim_value": "engineering",
  "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
  "role": "admin"
}

Response

{
  "id": "fr_01hqx8x7x7x7x7x7x7x7x7x",
  "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "issuer_id": "iss_01hqx8x7x7x7x7x7x7x7x7x",
  "claim_name": "groups",
  "claim_value": "engineering",
  "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
  "role": "admin",
  "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
  "created_at": "2026-08-13T18:00:00Z",
  "updated_at": "2026-08-13T18:00:00Z"
}

Valid roles are owner, admin, and member. Omit workspace_id for organization-level role assignment.

List rules

curl -X GET https://api.allternit.com/api/v1/admin/federation/rules \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "items": [
    {
      "id": "fr_01hqx8x7x7x7x7x7x7x7x7x",
      "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
      "issuer_id": "iss_01hqx8x7x7x7x7x7x7x7x7x",
      "claim_name": "groups",
      "claim_value": "engineering",
      "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
      "role": "admin",
      "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
      "created_at": "2026-08-13T18:00:00Z",
      "updated_at": "2026-08-13T18:00:00Z"
    }
  ]
}

Update an issuer

curl -X PUT https://api.allternit.com/api/v1/admin/federation/issuers/iss_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_url": "https://auth.example.com",
    "enabled": false
  }'

Update a rule

curl -X PUT https://api.allternit.com/api/v1/admin/federation/rules/fr_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claim_name": "groups",
    "claim_value": "platform",
    "role": "member"
  }'

claim_name and claim_value must be updated together.

Delete an issuer

curl -X DELETE https://api.allternit.com/api/v1/admin/federation/issuers/iss_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "deleted": true
}

Deleting an issuer cascades to its mapping rules.

Error codes

Status	Code	Description
`400`	`invalid_issuer_url`	Issuer URL must use `https://` and be ≤ 512 characters.
`400`	`invalid_claim_name`	Claim name must be 1–128 characters.
`400`	`invalid_claim_value`	Claim value must be 1–512 characters.
`400`	`invalid_claim`	`claim_name` and `claim_value` must be updated together.
`400`	`invalid_role`	Role must be `owner`, `admin`, or `member`.
`403`	`organization_required`	Caller is not associated with an organization.
`403`	`insufficient_role`	Caller is not an organization owner or admin.
`404`	`issuer_not_found`	Issuer does not exist or belongs to another organization.
`404`	`rule_not_found`	Mapping rule does not exist or belongs to another organization.

Workspaces — workspace roles and membership
RBAC — custom roles and groups
Security / SCIM — directory provisioning

Get Started

Core Concepts

Gizzi Code CLI

Tools & ACI

Security & Enterprise

Admin API

BYOC Runtime

Surfaces

CI CD

Guides

Cookbooks

Release Notes

Federation

Federation

Base URL

Issuer endpoints

Rule endpoints

Add an issuer

Request body

Response

Add a mapping rule

Request body

Response

List rules

Response

Update an issuer

Update a rule

Delete an issuer

Response

Error codes

​Federation

​Base URL

​Issuer endpoints

​Rule endpoints

​Add an issuer

​Request body

​Response

​Add a mapping rule

​Request body

​Response

​List rules

​Response

​Update an issuer

​Update a rule

​Delete an issuer

​Response

​Error codes

​Related pages

Federation

Base URL

Issuer endpoints

Rule endpoints

Add an issuer

Request body

Response

Add a mapping rule

Request body

Response

List rules

Response

Update an issuer

Update a rule

Delete an issuer

Response

Error codes

Related pages