# sso-api ## Pages - [EZGH SSO API](https://docs.ezghcloud.com/sso-api/index.md) — EZGH SSO's management API: the organization's workforce directory and its users, groups and sessions; verified email domains and upstream identity providers (OIDC and SAML) for federated sign-in; applications that sign in through the directory (OIDC, SAML 2.0 and EZGH apps), their assignments, client secrets and outbound SCIM provisioning; the application catalog; directory SCIM tokens; custom domains; and branding. Directory users sign in at https://.sso.ezgh.app (or a custom domain), whose OpenID Connect, OAuth and SAML endpoints are standards-defined and documented separately. Inbound SCIM 2.0 (https://sso.ezghcloud.com/scim/v2, RFC 7644, a directory SCIM token only) describes itself through its discovery endpoints. - [Assign users and groups to an application](https://docs.ezghcloud.com/sso-api/AddAssignments/index.md) — Ones already assigned are left as they are. - [Add users to a group](https://docs.ezghcloud.com/sso-api/AddGroupMembers/index.md) — Users already in it are left as they are. Every ID must be a user of this directory. - [Create an application](https://docs.ezghcloud.com/sso-api/CreateApplication/index.md) — An oidc application is an OpenID Connect client of the directory's issuer; its client ID is its id. A web application that authenticates with a secret gets its first ezgh_scs_ secret in this response, once. A saml application is a SAML 2.0 service provider; the directory gets its SAML signing certificate with its first one. Counts against sso.applications.count. An ezgh application with product console is the console application (directory users federating into the EZGH console by assuming bots): at most one per directory (409 console_application_exists), its tile opens the directory's /console/start, and the directory gets its SAML signing certificate with it. - [Create a client secret](https://docs.ezghcloud.com/sso-api/CreateApplicationSecret/index.md) — For rotation: an application holds at most two secrets (409 too_many_secrets). 409 secret_not_used unless it authenticates with client_secret_basic or client_secret_post. - [Add a custom domain](https://docs.ezghcloud.com/sso-api/CreateCustomDomain/index.md) — A hostname the customer owns (such as login.example.com) where the directory is served besides .sso.ezgh.app, as its own OIDC issuer and SAML entity. It starts pending, with the two records to create: a TXT record proving ownership and a CNAME to .sso.ezgh.app. sso-worker checks both at once, then every 15 minutes for a week; once both are found it has a certificate issued (ACME HTTP-01) and attached, and the domain becomes active. A hostname is claimed by one directory at a time. A directory has one custom domain: another hostname is 409 too_many_custom_domains until it's removed. While it's active, the pages people open directly on .sso.ezgh.app (the portal, sign-in, account, activation and reset links) redirect to it, and emails link to it; the OIDC and SAML endpoints there keep working. - [Create the organization's directory](https://docs.ezghcloud.com/sso-api/CreateDirectory/index.md) - [Add an email domain](https://docs.ezghcloud.com/sso-api/CreateDomain/index.md) — The domain starts pending, with the TXT record to publish. sso-worker looks for the record at once, then every 15 minutes for a week, and rechecks a verified domain every 6 hours. A domain is verified in only one directory at a time. - [Create a group](https://docs.ezghcloud.com/sso-api/CreateGroup/index.md) — 409 group_name_taken when another group has the name (any case). - [Add an identity provider](https://docs.ezghcloud.com/sso-api/CreateIdentityProvider/index.md) — OIDC (authorization code with PKCE) or SAML (SP-initiated, signed responses and assertions). Upstream metadata and keys are fetched by sso-worker through the hardened egress, within seconds and then every 6 hours. - [Create a directory SCIM token](https://docs.ezghcloud.com/sso-api/CreateScimToken/index.md) — The token is in this response only; only its SHA-256 is kept. - [Create a hosted user](https://docs.ezghcloud.com/sso-api/CreateUser/index.md) — The user starts pendingActivation and is sent an activation email. 409 email_taken when another user has the address. - [Delete an application](https://docs.ezghcloud.com/sso-api/DeleteApplication/index.md) — Ends every grant and token it holds, its secrets and its assignments. - [Remove an application's logo](https://docs.ezghcloud.com/sso-api/DeleteApplicationLogo/index.md) — The tile goes back to its EZGH product's mark or its monogram. No logo is 404. - [Delete a client secret](https://docs.ezghcloud.com/sso-api/DeleteApplicationSecret/index.md) — It stops working at once. - [Remove a custom domain](https://docs.ezghcloud.com/sso-api/DeleteCustomDomain/index.md) — sso-edge stops serving the hostname, and its issuer, at once; sso-worker then deletes its certificate and listener. - [Delete the directory](https://docs.ezghcloud.com/sso-api/DeleteDirectory/index.md) — Deletes every user and group in it (org-api is told, to drop their policy attachments), revokes its SCIM tokens and retires its alias for good. - [Remove the directory's logo](https://docs.ezghcloud.com/sso-api/DeleteDirectoryLogo/index.md) - [Remove an email domain](https://docs.ezghcloud.com/sso-api/DeleteDomain/index.md) — Its verification and routing end at once. - [Delete a group](https://docs.ezghcloud.com/sso-api/DeleteGroup/index.md) — org-api is told to drop its policy attachments. - [Remove an identity provider](https://docs.ezghcloud.com/sso-api/DeleteIdentityProvider/index.md) — Its domains sign in hosted, SCIM tokens naming it are revoked, its links and the memberships its group mappings added are removed. - [Revoke a directory SCIM token](https://docs.ezghcloud.com/sso-api/DeleteScimToken/index.md) - [Delete a user](https://docs.ezghcloud.com/sso-api/DeleteUser/index.md) — Removes their memberships, factors and sessions; org-api is told to drop their policy attachments. - [Get an application](https://docs.ezghcloud.com/sso-api/GetApplication/index.md) - [Get a custom domain](https://docs.ezghcloud.com/sso-api/GetCustomDomain/index.md) - [Get the organization's directory](https://docs.ezghcloud.com/sso-api/GetDirectory/index.md) - [Get an email domain](https://docs.ezghcloud.com/sso-api/GetDomain/index.md) - [Get a group](https://docs.ezghcloud.com/sso-api/GetGroup/index.md) - [Get an identity provider](https://docs.ezghcloud.com/sso-api/GetIdentityProvider/index.md) - [Get an application's outbound SCIM provisioning](https://docs.ezghcloud.com/sso-api/GetProvisioning/index.md) — Settings (never the bearer token) and status, with the settings' ETag. An ezgh application isn't provisioned (409 provisioning_not_supported). - [Get a user](https://docs.ezghcloud.com/sso-api/GetUser/index.md) - [List the directory's applications, newest first](https://docs.ezghcloud.com/sso-api/ListApplications/index.md) - [List who is assigned to an application](https://docs.ezghcloud.com/sso-api/ListAssignments/index.md) — The whole list (at most 1,000), newest first, with its ETag. Assignments are the directory's decision, checked at every authorization request; they're never IAM. - [List the application catalog](https://docs.ezghcloud.com/sso-api/ListCatalogApplications/index.md) — A curated list of common SaaS applications with their SAML and OIDC settings and SCIM mappings, embedded in the service and checked against each vendor's documentation (cited in sources). The console prefills a new application from it. Not recorded in Trails. - [List the directory's custom domains, newest first](https://docs.ezghcloud.com/sso-api/ListCustomDomains/index.md) - [List the directory's email domains, newest first](https://docs.ezghcloud.com/sso-api/ListDomains/index.md) - [List a group's members, most recently added first](https://docs.ezghcloud.com/sso-api/ListGroupMembers/index.md) - [List the directory's groups, newest first](https://docs.ezghcloud.com/sso-api/ListGroups/index.md) - [List the directory's identity providers, newest first](https://docs.ezghcloud.com/sso-api/ListIdentityProviders/index.md) - [List each pushed group's status, newest first](https://docs.ezghcloud.com/sso-api/ListProvisionedGroups/index.md) - [List each user's provisioning status, newest first](https://docs.ezghcloud.com/sso-api/ListProvisionedUsers/index.md) - [List the directory's SCIM tokens, newest first](https://docs.ezghcloud.com/sso-api/ListScimTokens/index.md) - [List a user's live SSO sessions, newest first](https://docs.ezghcloud.com/sso-api/ListSessions/index.md) — Sessions on the directory's portal host, under the directory's current session length and idle timeout. Never shows a session token. - [List the groups a user is in, most recently joined first](https://docs.ezghcloud.com/sso-api/ListUserGroups/index.md) - [List the directory's users, newest first](https://docs.ezghcloud.com/sso-api/ListUsers/index.md) - [Reactivate a suspended user](https://docs.ezghcloud.com/sso-api/ReactivateUser/index.md) — Active again if they had activated, otherwise pendingActivation with a new activation email. 409 user_not_suspended. - [Reconcile an application's provisioned users now](https://docs.ezghcloud.com/sso-api/ReconcileProvisioning/index.md) — sso-worker lists the application's users within seconds and repairs drift in the users EZGH SSO created (never others); it also pushes everyone assigned who isn't there yet. It runs weekly on its own. 409 provisioning_not_enabled when provisioning isn't configured and enabled. - [Fetch the upstream metadata and keys now](https://docs.ezghcloud.com/sso-api/RefreshIdentityProviderMetadata/index.md) - [Unassign users and groups](https://docs.ezghcloud.com/sso-api/RemoveAssignments/index.md) — Ones not assigned are ignored. Their existing grants end at their next refresh. - [Remove users from a group](https://docs.ezghcloud.com/sso-api/RemoveGroupMembers/index.md) — Users not in it are ignored. - [Send a new activation email](https://docs.ezghcloud.com/sso-api/ResendActivation/index.md) — Invalidates any unused activation link. 409 user_not_pending_activation, user_not_hosted. - [Reset a user's sign-in factors](https://docs.ezghcloud.com/sso-api/ResetUserFactors/index.md) — Removes their password, TOTP and passkeys, ends their sessions and emails a single-use link to enroll again. Hosted, active users only (409 user_not_hosted, user_not_active). - [Sign a user out of every SSO session](https://docs.ezghcloud.com/sso-api/RevokeSessions/index.md) — Revokes every session and unfinished sign-in, effective on the user's next request. Answers how many sessions were live. - [Suspend a user](https://docs.ezghcloud.com/sso-api/SuspendUser/index.md) — Ends their sessions and unused links at once. 409 user_suspended when already suspended. - [Change an application](https://docs.ezghcloud.com/sso-api/UpdateApplication/index.md) — kind, oidc.applicationType and ezgh.product can't change. Changing jwksUri drops the keys fetched from the old one. - [Upload an application's logo](https://docs.ezghcloud.com/sso-api/UpdateApplicationLogo/index.md) — The portal shows it on the application's tile, instead of its EZGH product's mark or its monogram. The image is re-encoded as a PNG and kept in EZGH SSO's object store; sso-edge serves it on the directory's own host. An application an EZGH product manages is 409 managed_by_product. - [Replace an application's assignments](https://docs.ezghcloud.com/sso-api/UpdateAssignments/index.md) — Every principal must be a user or group of this directory. Take If-Match with the list's ETag. - [Change the directory](https://docs.ezghcloud.com/sso-api/UpdateDirectory/index.md) — Every field is optional; only the ones given change. branding.logoUrl is read-only. - [Upload the directory's logo](https://docs.ezghcloud.com/sso-api/UpdateDirectoryLogo/index.md) - [Change a group](https://docs.ezghcloud.com/sso-api/UpdateGroup/index.md) - [Change an identity provider](https://docs.ezghcloud.com/sso-api/UpdateIdentityProvider/index.md) - [Replace an application's outbound SCIM provisioning](https://docs.ezghcloud.com/sso-api/UpdateProvisioning/index.md) — A whole-object replace: fields left out take their defaults, except the bearer token, which is kept (required on the first PUT and when baseUrl changes). Changing baseUrl starts over at the new URL; nothing is deprovisioned at the old one. Take If-Match with the settings' ETag. - [Change a user's profile](https://docs.ezghcloud.com/sso-api/UpdateUser/index.md) — 409 managed_by_scim for a user the identity provider's SCIM manages. - [Check the custom domain's DNS records now](https://docs.ezghcloud.com/sso-api/VerifyCustomDomain/index.md) — sso-worker checks the TXT and CNAME records within seconds instead of on its schedule; read the custom domain again for the outcome. - [Check the domain's TXT record now](https://docs.ezghcloud.com/sso-api/VerifyDomain/index.md) — sso-worker checks within seconds instead of on its schedule; read the domain again for the outcome. - [Application](https://docs.ezghcloud.com/sso-api/schemas/Application/index.md) — An application. Exactly one of oidc, saml and ezgh is set, by kind. A saml application is a SAML 2.0 service provider of the directory's IdP. An ezgh application is a portal tile and its resource-token settings: using the product is an EZGH action that IAM decides, so its assignments only decide who sees the tile. The one a product manages (managedBy mcpcentral) is also its portal's OAuth client in the directory: its id is the client_id, it authenticates with private_key_jwt against the product's JWKS, and it gets only resource tokens bound to the product's per-organization label. - [ApplicationCreate](https://docs.ezghcloud.com/sso-api/schemas/ApplicationCreate/index.md) - [ApplicationList](https://docs.ezghcloud.com/sso-api/schemas/ApplicationList/index.md) - [ApplicationUpdate](https://docs.ezghcloud.com/sso-api/schemas/ApplicationUpdate/index.md) - [Assignment](https://docs.ezghcloud.com/sso-api/schemas/Assignment/index.md) - [AssignmentList](https://docs.ezghcloud.com/sso-api/schemas/AssignmentList/index.md) - [AssignmentsChange](https://docs.ezghcloud.com/sso-api/schemas/AssignmentsChange/index.md) - [AssignmentsReplace](https://docs.ezghcloud.com/sso-api/schemas/AssignmentsReplace/index.md) - [AttributeMapping](https://docs.ezghcloud.com/sso-api/schemas/AttributeMapping/index.md) — One SCIM attribute written from the directory user. target is a SCIM path: attribute, attribute.subAttribute, attribute[type eq "type"].subAttribute, or an extension's urn:…:attribute. source is text with ${user.id}, ${user.email}, ${user.name}, ${user.givenName}, ${user.familyName}, ${user.department}, ${user.slug} or ${user.tags.}; a value that comes out empty isn't sent. id, externalId (always the user's ID), active, meta, schemas, groups, members and password are never mapped. - [Branding](https://docs.ezghcloud.com/sso-api/schemas/Branding/index.md) - [BrandingInput](https://docs.ezghcloud.com/sso-api/schemas/BrandingInput/index.md) - [Catalog](https://docs.ezghcloud.com/sso-api/schemas/Catalog/index.md) - [CatalogEntry](https://docs.ezghcloud.com/sso-api/schemas/CatalogEntry/index.md) - [CatalogParameter](https://docs.ezghcloud.com/sso-api/schemas/CatalogParameter/index.md) - [ClientSecret](https://docs.ezghcloud.com/sso-api/schemas/ClientSecret/index.md) - [CreatedApplication](https://docs.ezghcloud.com/sso-api/schemas/CreatedApplication/index.md) - [CreatedClientSecret](https://docs.ezghcloud.com/sso-api/schemas/CreatedClientSecret/index.md) - [CreatedScimToken](https://docs.ezghcloud.com/sso-api/schemas/CreatedScimToken/index.md) - [CustomDomain](https://docs.ezghcloud.com/sso-api/schemas/CustomDomain/index.md) - [CustomDomainCreate](https://docs.ezghcloud.com/sso-api/schemas/CustomDomainCreate/index.md) - [CustomDomainList](https://docs.ezghcloud.com/sso-api/schemas/CustomDomainList/index.md) - [CustomDomainRecord](https://docs.ezghcloud.com/sso-api/schemas/CustomDomainRecord/index.md) - [Deleted](https://docs.ezghcloud.com/sso-api/schemas/Deleted/index.md) - [Directory](https://docs.ezghcloud.com/sso-api/schemas/Directory/index.md) - [DirectoryCreate](https://docs.ezghcloud.com/sso-api/schemas/DirectoryCreate/index.md) - [DirectoryUpdate](https://docs.ezghcloud.com/sso-api/schemas/DirectoryUpdate/index.md) - [Domain](https://docs.ezghcloud.com/sso-api/schemas/Domain/index.md) - [DomainCreate](https://docs.ezghcloud.com/sso-api/schemas/DomainCreate/index.md) - [DomainList](https://docs.ezghcloud.com/sso-api/schemas/DomainList/index.md) - [Error](https://docs.ezghcloud.com/sso-api/schemas/Error/index.md) — Every non-2xx answer. Clients branch on code, never on message. - [EzghSettings](https://docs.ezghcloud.com/sso-api/schemas/EzghSettings/index.md) - [EzghSettingsInput](https://docs.ezghcloud.com/sso-api/schemas/EzghSettingsInput/index.md) - [Group](https://docs.ezghcloud.com/sso-api/schemas/Group/index.md) - [GroupCreate](https://docs.ezghcloud.com/sso-api/schemas/GroupCreate/index.md) - [GroupList](https://docs.ezghcloud.com/sso-api/schemas/GroupList/index.md) - [GroupMapping](https://docs.ezghcloud.com/sso-api/schemas/GroupMapping/index.md) - [GroupMembers](https://docs.ezghcloud.com/sso-api/schemas/GroupMembers/index.md) - [GroupUpdate](https://docs.ezghcloud.com/sso-api/schemas/GroupUpdate/index.md) - [IdentityProvider](https://docs.ezghcloud.com/sso-api/schemas/IdentityProvider/index.md) - [IdentityProviderCreate](https://docs.ezghcloud.com/sso-api/schemas/IdentityProviderCreate/index.md) - [IdentityProviderList](https://docs.ezghcloud.com/sso-api/schemas/IdentityProviderList/index.md) - [IdentityProviderUpdate](https://docs.ezghcloud.com/sso-api/schemas/IdentityProviderUpdate/index.md) - [IdpOidc](https://docs.ezghcloud.com/sso-api/schemas/IdpOidc/index.md) - [IdpOidcInput](https://docs.ezghcloud.com/sso-api/schemas/IdpOidcInput/index.md) - [IdpSaml](https://docs.ezghcloud.com/sso-api/schemas/IdpSaml/index.md) - [IdpSamlInput](https://docs.ezghcloud.com/sso-api/schemas/IdpSamlInput/index.md) - [LogoUpload](https://docs.ezghcloud.com/sso-api/schemas/LogoUpload/index.md) - [OidcSettings](https://docs.ezghcloud.com/sso-api/schemas/OidcSettings/index.md) - [OidcSettingsInput](https://docs.ezghcloud.com/sso-api/schemas/OidcSettingsInput/index.md) — On create, applicationType and redirectUris are required; on update, only the fields sent change (null clears a nullable one). - [ProvisionedGroup](https://docs.ezghcloud.com/sso-api/schemas/ProvisionedGroup/index.md) - [ProvisionedGroupList](https://docs.ezghcloud.com/sso-api/schemas/ProvisionedGroupList/index.md) - [ProvisionedUser](https://docs.ezghcloud.com/sso-api/schemas/ProvisionedUser/index.md) - [ProvisionedUserList](https://docs.ezghcloud.com/sso-api/schemas/ProvisionedUserList/index.md) - [Provisioning](https://docs.ezghcloud.com/sso-api/schemas/Provisioning/index.md) - [ProvisioningReplace](https://docs.ezghcloud.com/sso-api/schemas/ProvisioningReplace/index.md) - [ProvisioningStatus](https://docs.ezghcloud.com/sso-api/schemas/ProvisioningStatus/index.md) - [QuotaExceeded](https://docs.ezghcloud.com/sso-api/schemas/QuotaExceeded/index.md) — quota_exceeded: the quota that refused the request. Never with Retry-After. - [RevokedSessions](https://docs.ezghcloud.com/sso-api/schemas/RevokedSessions/index.md) - [SamlAttribute](https://docs.ezghcloud.com/sso-api/schemas/SamlAttribute/index.md) - [SamlIdp](https://docs.ezghcloud.com/sso-api/schemas/SamlIdp/index.md) — The directory's identity provider for this application, on its host. - [SamlSettings](https://docs.ezghcloud.com/sso-api/schemas/SamlSettings/index.md) - [SamlSettingsInput](https://docs.ezghcloud.com/sso-api/schemas/SamlSettingsInput/index.md) — On create, entityId and acsUrls are required unless metadata gives them; on update, only the fields sent change (null clears a nullable one). - [SamlSigningCertificate](https://docs.ezghcloud.com/sso-api/schemas/SamlSigningCertificate/index.md) — One of the directory's SAML signing certificates (RSA-3072, self-signed, valid three years). - [ScimToken](https://docs.ezghcloud.com/sso-api/schemas/ScimToken/index.md) - [ScimTokenCreate](https://docs.ezghcloud.com/sso-api/schemas/ScimTokenCreate/index.md) - [ScimTokenList](https://docs.ezghcloud.com/sso-api/schemas/ScimTokenList/index.md) - [Session](https://docs.ezghcloud.com/sso-api/schemas/Session/index.md) - [SessionList](https://docs.ezghcloud.com/sso-api/schemas/SessionList/index.md) - [SignInPolicy](https://docs.ezghcloud.com/sso-api/schemas/SignInPolicy/index.md) - [SpCertificate](https://docs.ezghcloud.com/sso-api/schemas/SpCertificate/index.md) - [User](https://docs.ezghcloud.com/sso-api/schemas/User/index.md) - [UserCreate](https://docs.ezghcloud.com/sso-api/schemas/UserCreate/index.md) - [UserList](https://docs.ezghcloud.com/sso-api/schemas/UserList/index.md) - [UserUpdate](https://docs.ezghcloud.com/sso-api/schemas/UserUpdate/index.md)