SSO (Single Sign-On) Configure SAML and OIDC single sign-on for your organization.
Admin endpoints require owner role and a Business plan or higher. Public auth endpoints are rate-limited but require no authentication. Base URL: https://api.airaproof.com/api/v1
Aira supports both SAML 2.0 and OIDC single sign-on. The flow works as follows:
The frontend calls SSO Check with the user's email to detect if SSO is enabled for their domain.
If enabled, the user is redirected to the SSO Login endpoint, which sends them to the identity provider (IdP).
After authentication, the IdP posts back to the ACS (SAML) or OIDC Callback endpoint.
Aira generates a one-time exchange code and redirects to the frontend.
The frontend calls SSO Exchange to swap the code for a JWT token.
Owners configure SSO via the admin endpoints at the bottom of this page.
GET /api/v1/auth/sso/check?email={email} Check if an email address belongs to a domain with SSO configured.
Field Type Required Description emailstring Yes Full email address to check
{ "sso_enabled" : true , "enforced" : false , "org_slug" : "acme-abc123" } Field Type Description sso_enabledboolean Whether SSO is configured for this email domain enforcedboolean Whether SSO is the only allowed login method org_slugstring or null Organization slug (only present when sso_enabled is true)
curl "https://api.airaproof.com/api/v1/auth/sso/check?email=jane@acme.com" GET /api/v1/auth/sso/login/{org_slug} Auto-detects the configured protocol (SAML or OIDC) and redirects the user to the identity provider. Returns a 302 redirect .
Field Type Required Description org_slugstring Yes Organization slug
curl -L "https://api.airaproof.com/api/v1/auth/sso/login/acme-abc123" Query Parameter Description error=org_not_foundOrganization does not exist error=sso_not_configuredSSO is not configured for this organization
POST /api/v1/auth/sso/acs Content-Type : application/x-www-form-urlencoded Receives the SAML response from the IdP. Validates the assertion, finds or creates the user, generates an exchange code, and redirects to the frontend at /sso/callback?code={code}.
This endpoint is called by the identity provider, not by your application directly.
Field Type Required Description SAMLResponsestring Yes Base64-encoded SAML response from IdP RelayStatestring No Organization slug (used to identify the org)
Query Parameter Description error=sso_validation_failedSAML response validation failed error=sso_failedOrganization not found or no valid assertion
GET /api/v1/auth/sso/oidc/login/{org_slug} Redirects to the OIDC authorization URL. Only works for organizations with OIDC configured. Returns a 302 redirect .
Field Type Required Description org_slugstring Yes Organization slug
curl -L "https://api.airaproof.com/api/v1/auth/sso/oidc/login/acme-abc123" Query Parameter Description error=org_not_foundOrganization does not exist error=sso_not_configuredOIDC is not configured for this organization
GET /api/v1/auth/sso/oidc/callback?code={code}&state={state} Handles the OIDC provider callback. Exchanges the authorization code for tokens, finds or creates the user, generates an exchange code, and redirects to the frontend at /sso/callback?code={code}.
This endpoint is called by the identity provider, not by your application directly.
Field Type Required Description codestring Yes Authorization code from the OIDC provider statestring Yes State parameter for CSRF protection
Query Parameter Description error=sso_failedOIDC token exchange or user creation failed
POST /api/v1/auth/sso/exchange Content-Type : application/json Exchange a one-time SSO code for a JWT token. The code is generated after successful SAML or OIDC authentication and is valid for a single use.
Field Type Required Description codestring Yes One-time exchange code from the SSO callback
{ "token" : "eyJ..." , "expires_in" : 86400 , "org_uuid" : "uuid" , "user_uuid" : "uuid" } Field Type Description tokenstring JWT access token expires_ininteger Token lifetime in seconds org_uuidstring Organization UUID user_uuidstring User UUID
curl -X POST https://api.airaproof.com/api/v1/auth/sso/exchange \ -H "Content-Type: application/json" \ -d '{"code": "abc123..."}' Status Code Description 400 SSO_EXCHANGE_ERROR Invalid, expired, or already-used code
GET /api/v1/auth/sso/metadata/{org_slug} Returns the SAML Service Provider metadata XML. Use this URL when configuring your identity provider.
Field Type Required Description org_slugstring Yes Organization slug
Returns application/xml content with the SP entity ID, ACS URL, and certificate.
curl "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" Status Description 404 Organization not found
POST /api/v1/sso/configure Authorization : Bearer <token> Content-Type : application/json Upload IdP metadata XML to configure SAML SSO. Requires owner role and Business plan or higher.
Field Type Required Description idp_metadata_xmlstring Yes Full IdP metadata XML string
{ "enabled" : true , "enforced" : false , "protocol" : "saml" , "idp_entity_id" : "https://idp.example.com/metadata" , "sp_entity_id" : "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" , "sp_acs_url" : "https://api.airaproof.com/api/v1/auth/sso/acs" , "sp_metadata_url" : "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" , "oidc_issuer_url" : null , "oidc_client_id" : null } curl -X POST https://api.airaproof.com/api/v1/sso/configure \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"idp_metadata_xml": "<?xml version=\"1.0\"?>..."}' Status Code Description 400 SSO_CONFIG_ERROR Invalid metadata XML 403 PLAN_REQUIRED Organization is not on Business plan or higher
POST /api/v1/sso/configure-oidc Authorization : Bearer <token> Content-Type : application/json Configure OIDC SSO with client credentials and issuer URL. Requires owner role and Business plan or higher.
Field Type Required Description client_idstring Yes OIDC client ID from your identity provider client_secretstring Yes OIDC client secret issuer_urlstring Yes OIDC issuer URL (e.g. https://accounts.google.com)
{ "enabled" : true , "enforced" : false , "protocol" : "oidc" , "idp_entity_id" : null , "sp_entity_id" : "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" , "sp_acs_url" : null , "sp_metadata_url" : null , "oidc_issuer_url" : "https://accounts.google.com" , "oidc_client_id" : "123456.apps.googleusercontent.com" } curl -X POST https://api.airaproof.com/api/v1/sso/configure-oidc \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "client_id": "123456.apps.googleusercontent.com", "client_secret": "GOCSPX-...", "issuer_url": "https://accounts.google.com" }' Status Code Description 400 SSO_CONFIG_ERROR Invalid credentials or unreachable issuer 403 PLAN_REQUIRED Organization is not on Business plan or higher
POST /api/v1/sso/enforce Authorization : Bearer <token> Content-Type : application/json Enable or disable SSO enforcement. When enforced, users with matching email domains must use SSO to log in. Requires owner role.
Field Type Required Description enforceboolean Yes true to require SSO, false to make it optional
{ "message" : "SSO enforcement enabled" } curl -X POST https://api.airaproof.com/api/v1/sso/enforce \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enforce": true}' Status Code Description 400 SSO_ENFORCE_ERROR SSO is not configured yet
GET /api/v1/sso Authorization : Bearer <token> Returns the current SSO configuration for your organization. Requires owner role.
{ "enabled" : true , "enforced" : false , "protocol" : "saml" , "idp_entity_id" : "https://idp.example.com/metadata" , "sp_entity_id" : "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" , "sp_acs_url" : "https://api.airaproof.com/api/v1/auth/sso/acs" , "sp_metadata_url" : "https://api.airaproof.com/api/v1/auth/sso/metadata/acme-abc123" , "oidc_issuer_url" : null , "oidc_client_id" : null } { "enabled" : false , "enforced" : false , "protocol" : null , "idp_entity_id" : null , "sp_entity_id" : null , "sp_acs_url" : null , "sp_metadata_url" : null , "oidc_issuer_url" : null , "oidc_client_id" : null } Field Type Description enabledboolean Whether SSO is configured enforcedboolean Whether SSO login is mandatory protocolstring or null "saml" or "oidc"idp_entity_idstring or null SAML IdP entity ID sp_entity_idstring or null Service Provider entity ID sp_acs_urlstring or null SAML Assertion Consumer Service URL sp_metadata_urlstring or null SP metadata XML URL oidc_issuer_urlstring or null OIDC issuer URL oidc_client_idstring or null OIDC client ID
curl https://api.airaproof.com/api/v1/sso \ -H "Authorization: Bearer <token>" DELETE /api/v1/sso Authorization : Bearer <token> Remove SSO configuration from the organization. This also disables enforcement. Requires owner role. Returns 204 No Content .
curl -X DELETE https://api.airaproof.com/api/v1/sso \ -H "Authorization: Bearer <token>"