Skip to main content

Partner API: Admin SSO & Provisioning

Configure SAML SSO for an organization's admins with just-in-time provisioning and role mapping.

Admin SSO and provisioning

Configure single sign-on for an organization's admins (the people who edit and publish handbooks), with just-in-time provisioning and role mapping, so you never have to invite admins manually.

PUT /organizations/{orgId}/sso/admin | Access token

{
  "protocol": "saml",
  "idp": {
    "entityId": "https://idp.acme.com/saml/metadata",
    "ssoUrl": "https://idp.acme.com/saml/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIID…\n-----END CERTIFICATE-----"
  },
  "jitProvisioning": true,
  "roleAttribute": "airmason_role",
  "roleMapping": {
    "hr-admin": "owner",
    "hr-editor": "handbook_editor",
    "people-ops": "admin"
  },
  "defaultRole": null,
  "enabled": true,
  "enforced": true
}

Field

Notes

protocol

saml only. oidc returns 400 unsupported_protocol; contact support if you need it.

idp

Your identity provider's entity ID, SSO URL and signing certificate (PEM). An expired or unparseable certificate is rejected with 400 (certificate is invalid or expired).

jitProvisioning

When true, an admin who signs in via SSO for the first time is created automatically with the mapped role — no invitation needed

roleAttribute

Name of the SAML attribute carrying the user's role

roleMapping

Your role values → AirMason roles. Exactly these values are accepted: owner, admin, handbook_editor, handbook_publisher, employee_admin, viewer. Custom organization roles are rejected.

defaultRole

Role for users whose attribute value has no mapping. null means such users are refused.

enabled

Defaults to true. Set false to keep the configuration but stop offering SSO. With enabled: false the enforced value is ignored rather than rejected: password sign-in is restored and the response reports enforced: false.

enforced

When true, password sign-in is removed from the organization's admin login methods. Any Okta or Microsoft sign-in method the organization already had is kept.

The response describes both sides of the handshake. The certificate is write-only: only its expiry comes back.

{
  "protocol": "saml",
  "enabled": true,
  "enforced": true,
  "idp": {
    "entityId": "https://idp.acme.com/saml/metadata",
    "ssoUrl": "https://idp.acme.com/saml/sso",
    "certificateExpiresAt": "2028-03-01T00:00:00.000Z"
  },
  "sp": {
    "entityId": "airmason-admin:1f2a7b3c-9d4e-4f5a-8b6c-0d1e2f3a4b5c",
    "acsUrl": "https://api.airmason.com/v1/sso/saml/partner/1f2a7b3c-9d4e-4f5a-8b6c-0d1e2f3a4b5c/login"
  },
  "jitProvisioning": true,
  "roleAttribute": "airmason_role",
  "roleMapping": { "hr-admin": "owner", "hr-editor": "handbook_editor", "people-ops": "admin" },
  "defaultRole": null
}

Configure sp.entityId (audience) and sp.acsUrl in your IdP. Both are per organization: sp.entityId is airmason-admin:<organization id> and sp.acsUrl is /v1/sso/saml/partner/<organization id>/login. If you reuse one identity-provider application across several tenants, make sure each assertion carries the audience of the organization it is for. Role changes in your IdP are applied on the user's next sign-in.

GET returns the current configuration in the same shape (404 when nothing is configured). DELETE returns 204, disables SSO, re-enables password login and erases the stored certificate.

Employee SSO

Employee-facing SSO (for the handbook portal) is configured at PUT /organizations/{orgId}/sso/employee with the same protocol, idp, enabled and enforced fields, but it is not configured the same way as admin SSO:

  • jitProvisioning, roleAttribute, roleMapping and defaultRole are rejected with 400 validation_error, and the response carries no role fields. Employees are matched to the records you created through the API.

  • sp.entityId and sp.acsUrl are both <portal url>/custom_saml/saml2, for example https://books.airmason.com/acme-corp/custom_saml/saml2.

Partner API documentation:

Related Articles
Did this answer your question?