Skip to content

Console single sign-on API

The console single sign-on API lets administrators of a tenant sign in to the Airgate console through their own identity provider (IdP): Microsoft Entra ID, Okta, Google, AD FS, Ping, Keycloak, or any SAML 2.0 or OpenID Connect provider. It backs Settings › Single sign-on. Password sign-in keeps working next to it.

Provider management routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. The sign-in routes are public and live under /api/v1/auth/sso/. See API overview for authentication.

Method Path Permission Purpose
GET /sso-providers admin:read List providers
GET /sso-providers/draft admin:write Reserve a provider ID and get the addresses to register at the IdP
POST /sso-providers admin:write Create a provider
POST /sso-providers/idp-metadata admin:write Preview parsed SAML IdP metadata
GET /sso-providers/test-results/{code} admin:read Result of a test sign-in
GET /sso-providers/{id} admin:read Read a provider
PUT /sso-providers/{id} admin:write Update a provider
DELETE /sso-providers/{id} admin:write Delete a provider
POST /api/v1/auth/sso/discover Public Find the provider for an email address
GET /api/v1/auth/sso/{id}/start Public Start a sign-in (redirect to the IdP)
GET /api/v1/auth/sso/{id}/metadata Public SAML service-provider metadata
POST /api/v1/auth/sso/{id}/acs Public SAML Assertion Consumer Service
GET /api/v1/auth/sso/{id}/callback Public OpenID Connect redirect URI
POST /api/v1/auth/sso/exchange Public Swap a one-time sign-in code for a console token

Every provider change is audited (object type sso_provider).

  1. The sign-in page posts the work email to POST /api/v1/auth/sso/discover. The email domain selects the provider; a domain belongs to one provider across the whole platform.
  2. The browser goes to GET /api/v1/auth/sso/{id}/start, which records the sign-in and redirects to the IdP.
  3. The IdP returns to the ACS URL (SAML, HTTP-POST binding) or the redirect URI (OpenID Connect, authorization code with PKCE). Airgate validates the signature, audience, issuer, time window and request ID or nonce, and accepts each response once. IdP-initiated SAML sign-in is not supported.
  4. Airgate checks the identity and finds or creates the administrator account. The browser lands on /login?sso_code=..., and the page swaps the code for a console token with POST /api/v1/auth/sso/exchange. A failure lands on /login?sso_error=... and is stored on the provider as last_error.
  • The asserted email must belong to one of the provider’s domains.
  • The role comes from role_mappings (IdP group to Airgate role), compared case-insensitively against the groups claim. When several mappings match, the strongest role wins: tenant_admin > network_admin > helpdesk > read_only > guest_operator. With no match, default_role applies; an empty default role means no access.
  • The first sign-in creates an administrator with no password. Later sign-ins update the name and role from the IdP. A user who lost every mapped group is refused.
  • An existing local administrator with the same email in the same tenant may sign in through SSO and keeps the role set in the console.
  • An email that belongs to an administrator of another tenant, or to a platform administrator, is refused.
  • Deleting a provider disables the administrators it created.
SAML attribute OpenID Connect claim
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, email, mail, emailAddress, urn:oid:0.9.2342.19200300.100.1.3, .../claims/name, .../claims/upn, then a NameID that is an email email, preferred_username, upn
Name http://schemas.microsoft.com/identity/claims/displayname, displayName, name, cn, then given name and surname name
Groups http://schemas.microsoft.com/ws/2008/06/identity/claims/groups, .../claims/role, groups, memberOf, role, roles, urn:oid:1.3.6.1.4.1.5923.1.5.1.1 groups, roles

Override them with config.email_claim, config.name_claim and config.groups_claim.

{
"id": "4b1f...", "tenant_id": "dc40...", "name": "Entra ID",
"protocol": "saml", "enabled": true,
"domains": ["contoso.com"],
"config": {
"idp_metadata_url": "https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml?appid=<app>",
"email_claim": "", "name_claim": "", "groups_claim": ""
},
"client_secret": "",
"role_mappings": [{"group": "Airgate-Admins", "role": "tenant_admin"}],
"default_role": "",
"users": 3,
"last_login_at": "...", "last_error": "", "last_error_at": null,
"created_at": "...", "updated_at": "...",
"sp": {
"entity_id": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../metadata",
"acs_url": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../acs",
"metadata_url": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../metadata",
"sign_on_url": "https://airgate.contoso.com/login"
},
"idp": {"entity_id": "...", "sso_url": "...", "certificates": [{"subject": "...", "not_after": "...", "sha256": "..."}]}
}
Field Type Meaning
id UUID Create only: the ID returned by GET /sso-providers/draft, so the addresses you already registered at the IdP stay valid
name string Required, at most 100 characters
protocol string saml or oidc. Cannot change after creation.
enabled boolean
domains array of string At least one email domain. It routes sign-ins to this provider and limits who it can sign in. A domain used by another provider returns 409.
config.idp_metadata_url / config.idp_metadata_xml string SAML: the IdP metadata URL (https) or the pasted metadata XML. The metadata must have an HTTP-Redirect sign-on URL and a signing certificate.
config.issuer string OpenID Connect: the issuer URL (https), for example https://login.microsoftonline.com/<tenant id>/v2.0
config.client_id string OpenID Connect: required
config.scopes string OpenID Connect: extra scopes, space separated
config.email_claim, config.name_claim, config.groups_claim string Override the default claim names
client_secret string OpenID Connect client secret. Encrypted at rest and never returned. On update, omit it or send null to keep the stored value.
role_mappings array {"group": "<IdP group or role>", "role": "<Airgate role>"}. Every mapping needs a group.
default_role string Role when no mapping matches; empty means no access. Either a mapping or a default role is required.

Roles are tenant_admin, network_admin, helpdesk, read_only and guest_operator. You can only map roles whose permissions you hold yourself.

sp lists what to register at the IdP: for SAML the Identifier (Entity ID), Reply URL (ACS URL) and metadata URL; for OpenID Connect the redirect_uri (.../auth/sso/{id}/callback). idp summarises the parsed SAML metadata. users counts the administrators the provider signed in.

A SAML metadata URL is fetched again at every save, so saving picks up a rolled signing certificate; if the IdP is unreachable, the stored copy is kept. Metadata URLs and OpenID Connect issuers must use https and may not point to private addresses.

Permission: admin:write

Query protocol=saml or protocol=oidc. Returns {"id": "...", "sp": {...}}: a new provider ID and the addresses to register at the IdP before you create the provider. Nothing is stored.

Permission: admin:write

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/sso-providers" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Entra ID", "protocol": "oidc", "enabled": true, "domains": ["contoso.com"],
"config": {"issuer": "https://login.microsoftonline.com/<tenant id>/v2.0", "client_id": "<application id>"},
"client_secret": "<client secret>",
"role_mappings": [{"group": "<group object id>", "role": "tenant_admin"}]}'

Returns 201 with the provider. 400 for a validation error (the message says what is missing), 409 when a domain belongs to another provider or the ID is taken.

Permission: admin:write

Same body as create. Returns 200 with the provider.

Permission: admin:write

Returns 204. The administrators the provider created are disabled.

Permission: admin:write

Body {"url": "https://..."} or {"xml": "<EntityDescriptor ...>"}. Returns the parsed IdP summary (entity_id, sso_url, certificates) so you can check it before saving.

The console opens /api/v1/auth/sso/{id}/start?test=1 (this works for a disabled provider too). After the IdP, the browser returns to Settings › Single sign-on with a test code, and the page reads the result.

Permission: admin:read

{"ok": true,
"identity": {"subject": "...", "email": "alice@contoso.com", "name": "Alice", "groups": ["Airgate-Admins"], "claims": {"...": ["..."]}},
"role": "tenant_admin", "matched_groups": ["Airgate-Admins"],
"account": "...what a real sign-in would do...", "at": "..."}

Nobody is signed in and no account changes during a test.

These routes need no token. Browsers call them during sign-in; you rarely call them yourself.

Body {"email": "alice@contoso.com"}. Returns {"provider_id", "name", "protocol", "start_url"}. Returns 404 when the domain has no enabled provider (Single sign-on is not set up for contoso.com. Sign in with your password.).

Query login_hint (the email, passed to the IdP) and test=1 for a test sign-in. Responds 302 to the IdP.

The SAML service-provider metadata (XML) to import at the IdP.

The SAML Assertion Consumer Service. The IdP posts the SAML response here.

The OpenID Connect redirect URI. The IdP returns the authorization code here.

Body {"code": "..."}. Returns {"token", "expires_at", "principal"}, the same as POST /api/v1/auth/login. Codes are single-use and expire after 2 minutes (401: this sign-in link expired; sign in again).

© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security