Documentation base URLs use placeholder https://{your-tenant}.sso.id. Log in to show your tenant or custom domain.
Log in for Your Tenant URL
Complete HTTP Reference (Auth.SSO.Id + Core.SSO.Id)

REST & Protocol API Reference

The complete architectural reference for every endpoint across the SSO.ID v2 Authorization & Federation Server (https://{your-tenant}.sso.id/auth) and the Core Management & Provisioning API (https://{your-tenant}.sso.id/api).

Base URLs & Headers OIDC, OAuth 2.0 & Passkeys SAML 2.0 Endpoints SCIM 2.0 Provisioning Applications & Keys Connections & IdPs Users, Roles & Groups Organizations & OUs Tenant, DNS & Billing Audit, SIEM & Compliance
Architecture Story

Two Specialized Engines, One Unified Identity Platform

To guarantee sub-50ms login redirects while scaling complex enterprise management operations, SSO.ID v2 separates runtime protocol execution from management plane APIs:

1. Protocol Engine (Auth.SSO.Id)

Base URL: https://{your-tenant}.sso.id/auth (or your verified Custom Domain e.g. https://login.acme.com)

Handles OIDC Discovery, JWKS public keys, OAuth 2.0 authorization & token exchange, SAML 2.0 IdP/SP bindings, and FIDO2 WebAuthn Passkey ceremonies.

2. Management & SCIM Engine (Core.SSO.Id)

Base URL: https://{your-tenant}.sso.id/api

Handles Applications, Connections, Users, Roles, Groups, Organizations, Organization Units, Multi-Factor, Tenant Governance, Custom Domains, SCIM 2.0, Audit Logs, and Compliance.

Flow Diagram Dual-Engine API Architecture ({your-tenant}.sso.id/auth vs {your-tenant}.sso.id/api)
flowchart TD subgraph Clients["Client Applications"] SPA["SPAs & Mobile Apps"] BE["Backend Services"] IDP["Enterprise IdP (SCIM)"] end subgraph Runtime["Runtime Protocol Engine ({your-tenant}.sso.id/auth)"] OIDC["/.well-known/openid-configuration"] JWKS["/.well-known/jwks.json"] AUTH["/auth/oauth/authorize"] PASSKEY["/auth/oauth/passkey/*"] SAML["/auth/Saml/Login"] end subgraph Management["Core Management API ({your-tenant}.sso.id/api)"] TOKEN["/auth/oauth/token & /api/oauth2/token"] APPS["/api/applications"] USERS["/api/users & /api/roles"] SCIM["/api/scim/v2 (RFC 7644)" ] AUDIT["/api/audit-logs & /api/compliance"] end SPA --> AUTH SPA --> PASSKEY BE --> TOKEN BE --> APPS BE --> USERS IDP --> SCIM BE --> AUDIT
Clients interact with {your-tenant}.sso.id/auth for high-throughput runtime logins and token exchanges, and {your-tenant}.sso.id/api for administrative REST & SCIM management.

Standard Request Headers for https://{your-tenant}.sso.id/api

Header Name Required Example Value Purpose
Authorization Yes (Protected APIs) Bearer eyJhbGciOiJSUzI1Ni... RS256-signed JWT Access Token or SCIM 2.0 Bearer Token (for /api/scim/v2/*).
X-Tenant-Id Recommended 8f9d2a1c-4b3e-4d5a-9c1b-7e2f8a6d4c10 Scopes Management API operations to the active Tenant Workspace when an admin manages multiple tenants.
X-Region Optional US or EU Routes requests to the US (us-east) or EU (eu-central Frankfurt GDPR) data residency cluster.
Content-Type Yes (POST/PUT/PATCH) application/json Use application/scim+json for SCIM 2.0 endpoints and application/x-www-form-urlencoded for OAuth2 token requests.

1. OpenID Connect, OAuth 2.0 & Passkey Endpoints (Auth.SSO.Id)

Runtime authentication endpoints hosted on https://{your-tenant}.sso.id/auth (with direct token issuance also available on https://{your-tenant}.sso.id/api/oauth2/token).

Method Endpoint Path Description & Key Parameters
GET /auth/.well-known/openid-configuration OIDC Discovery metadata document. Optional query: ?appId={applicationId}. (Also aliased at /api/oidc/openid-configuration).
GET /auth/.well-known/jwks.json JSON Web Key Set (JWKS) containing active RSA/ECDSA public keys (kid, n, e, alg, use) for verifying JWT signatures. Optional query: ?appId={applicationId}. (Also aliased at /api/oidc/jwks).
GET /auth/oauth/authorize Initiates interactive OAuth 2.0 / OIDC login. Supports client_id, response_type=code|token|id_token, redirect_uri, scope, state, code_challenge, code_challenge_method=S256, organizationId, organizationUnitId, connectionId, tenant_id, login_hint.
POST /auth/oauth/token Exchanges authorization code, refresh token, user credentials, or client credentials for JWT tokens. Supports grant_type=authorization_code | refresh_token | password | client_credentials.
POST https://{your-tenant}.sso.id/api/oauth2/token Direct Core API OAuth 2.0 token issuance endpoint supporting JSON and form-urlencoded payloads for confidential backends and M2M services.
GET /auth/oauth/userinfo Returns standard OIDC claims (sub, name, email, email_verified, picture, roles) for the authenticated Bearer access token.
GET / POST /auth/oauth/logout RP-Initiated Single Logout. Clears SSO session and redirects to post_logout_redirect_uri when validated with id_token_hint.
POST /auth/oauth/passkey/register-begin Generates FIDO2 WebAuthn PublicKeyCredentialCreationOptions challenge for enrolling a new biometric or hardware passkey.
POST /auth/oauth/passkey/register-complete Verifies attestation response from navigator.credentials.create() and persists the public key credential on the user profile.
POST /auth/oauth/passkey/auth-begin Generates FIDO2 WebAuthn PublicKeyCredentialRequestOptions challenge for passwordless passkey sign-in.
POST /auth/oauth/passkey/auth-complete Verifies cryptographic signature from navigator.credentials.get() and issues an authenticated SSO session / authorization grant.

2. SAML 2.0 Identity Provider & Service Provider Endpoints

Method Endpoint Path Role Description
GET https://{your-tenant}.sso.id/auth/saml/metadata?appId={id} IdP Returns signed SAML 2.0 Identity Provider Metadata XML (EntityDescriptor, KeyDescriptor X.509 cert, SingleSignOnService, SingleLogoutService) for a specific Application.
GET https://{your-tenant}.sso.id/auth/saml/GetIDPMetadataBase64?appId={id} IdP Returns the Application's SAML 2.0 IdP Metadata encoded as Base64 for automated SDK/CLI provisioning.
GET / POST https://{your-tenant}.sso.id/auth/Saml/Login IdP SAML 2.0 Single Sign-On endpoint. Accepts SAMLRequest and RelayState via HTTP-Redirect (Deflate + Base64 query string) or HTTP-POST binding.
GET / POST https://{your-tenant}.sso.id/auth/saml/logout IdP / SP SAML 2.0 Single Logout (SLO) endpoint (also routed at /auth/saml/slo).
POST / GET https://{your-tenant}.sso.id/auth/saml/acs SP Assertion Consumer Service (ACS) endpoint where external Enterprise SAML IdPs (Okta, Azure AD, Ping) POST signed SAMLResponse assertions.
GET https://{your-tenant}.sso.id/auth/Saml/SPMetadata SP Downloads SSO.ID's SAML 2.0 Service Provider (SP) Metadata XML for uploading into an external Enterprise IdP.

3. SCIM 2.0 Provisioning Endpoints (Core.SSO.Id)

All SCIM 2.0 endpoints are available at both the tenant root https://{your-tenant}.sso.id/api/scim/v2/* and connection-scoped https://{your-tenant}.sso.id/api/scim/v2/connections/{connectionId}/*. Authenticate with Authorization: Bearer {scim_token}.

Method Endpoint Path SCIM 2.0 Operation (RFC 7643 / RFC 7644)
GET /api/scim/v2/ServiceProviderConfig Returns SCIM 2.0 Service Provider Configuration capabilities (PATCH, filter, sort, pagination).
GET /api/scim/v2/Schemas Returns supported SCIM 2.0 schemas (User and Group).
GET /api/scim/v2/ResourceTypes Returns SCIM resource type descriptors for Users and Groups.
GET /api/scim/v2/Users Lists or filters provisioned users (e.g., ?filter=userName eq "[email protected]"&startIndex=1&count=100).
GET /api/scim/v2/Users/{id} Retrieves a single SCIM 2.0 User resource by ID.
POST /api/scim/v2/Users Provisions a new user with attribute mappings and optional JIT group/role assignment.
PUT /api/scim/v2/Users/{id} Replaces all attributes of an existing SCIM User resource.
PATCH /api/scim/v2/Users/{id} Applies SCIM PatchOp operations (e.g., {"op":"replace","path":"active","value":false} to suspend an offboarded employee).
DELETE /api/scim/v2/Users/{id} Deprovisions a user according to the connection's deprovision policy (suspend, revoke sessions, or delete).
GET /api/scim/v2/Groups Lists SCIM 2.0 Groups (/api/scim/v2/Groups/{id} retrieves a single group).
POST /api/scim/v2/Groups Creates a SCIM 2.0 Group and syncs member user IDs. (Also supports PUT /Groups/{id} and DELETE /Groups/{id}).

4. Applications, App Pages, APIs & Signing Keys (Core.SSO.Id)

Method Endpoint Path Description
GET /api/applications Lists all registered applications in the current tenant with pagination and search filters.
POST /api/applications Creates a new Application (SPA, Web, Native, M2M, or SAML 2.0) and generates clientId, clientSecret, and signing key pair.
GET /api/applications/{id} Retrieves full configuration for an Application, including protocol settings, Redirect URIs, token lifetimes, override flags, and custom claims.
PUT /api/applications/{id} Updates an Application's settings, branding overrides, security policies, token lifetimes, or SAML/OIDC configurations.
DELETE /api/applications/{id} Deletes an Application and revokes its active client credentials.
GET / POST /api/applications/{id}/menus Retrieves or creates hierarchical App Pages / Navigation Menus for dynamic frontend rendering and CRUD permission assignment. (Also supports PUT /api/applications/{id}/menus/{menuId} and DELETE).
GET / POST /api/applications/{id}/apis Lists or registers backend API endpoints belonging to the Application so Roles can be granted granular API-level access. (Also supports PUT and DELETE /api/applications/{id}/apis/{apiId}).
GET / POST /api/applications/{id}/connections Lists or enables identity connections (Google, GitHub, Okta SAML, Azure AD OIDC) for the Application. (DELETE /api/applications/{id}/connections/{connectionId} disables a connection).
GET / PUT /api/applications/{id}/factors Gets or updates enabled Multi-Factor Authentication factors (TOTP, Email OTP, SMS, Passkeys) for the Application.
GET / POST /api/applications/{id}/organizations Lists or links B2B Customer Organizations authorized to access this Application.
GET / POST /api/applications/{id}/users Lists or assigns specific Users directly to the Application (DELETE /api/applications/{id}/users/{userId} removes access).
GET /api/applications/metadata?id={id} Downloads SAML 2.0 / OIDC Federation Metadata XML for the specified Application.
GET /api/applications/certificate?id={id} Downloads the X.509 signing certificate (.cer / .pem) for the Application.
GET /api/signing-keys Lists all cryptographic signing keys (active, previous, and revoked) across the tenant.
POST /api/signing-keys/rotate Performs zero-downtime cryptographic key rotation, promoting a new primary key while retaining the previous key in JWKS for token verification grace periods.
POST /api/signing-keys/import Imports a custom PEM/PFX X.509 signing certificate and private key.
POST /api/signing-keys/revoke/{id} Immediately revokes a compromised signing key and removes it from JWKS.
GET /api/signing-keys/download-cert/{id} Downloads the public X.509 certificate for a specific signing key ID.

5. Identity Connections & Live Testing (Core.SSO.Id)

Method Endpoint Path Description
GET /api/connections Lists all configured OAuth 2.0, OpenID Connect, and SAML 2.0 connections in the tenant.
GET /api/connections/defaults Returns pre-configured templates for popular providers (Google, GitHub, Microsoft, Apple, LinkedIn, Facebook, Okta, Auth0, Keycloak).
POST /api/connections Creates a new Identity Connection including protocol endpoints, attribute mappings, group/role mappings, and SCIM provisioning rules.
PUT /api/connections/{id} Updates an existing Identity Connection. (DELETE /api/connections/{id} removes it).
POST /api/connections/test Pre-Create Live Connection Test: Initiates a sandboxed handshake against an external OAuth2/OIDC/SAML provider before saving the connection to verify credentials and inspect live claims.
GET /api/connections/{id}/health Checks real-time reachability, discovery document validity, and certificate expiration of a saved connection.
GET /api/connections/sp-metadata Returns SSO.ID's SAML 2.0 Service Provider (SP) Metadata XML for configuring external enterprise IdPs.
GET /api/connections/sp-certificate Downloads SSO.ID's SAML SP X.509 signing/encryption certificate.

6. Users, Roles, Menus & Groups (Core.SSO.Id)

Method Endpoint Path Description
GET / POST /api/users Lists directory users (with pagination/filtering) or creates a new user account directly.
POST /api/users/invite Sends an email invitation link to onboard a user (POST /api/users/{userId}/resend-invite resends the token).
GET / PUT /api/users/self Retrieves or updates the currently authenticated user's own profile (POST /api/users/self/change-password updates password).
GET /api/users/current/applications Returns all Applications the logged-in user is authorized to launch in the End-User App Launcher Portal.
GET /api/users/{userId}/sessions Lists all active device/browser sessions for a user (DELETE /api/users/{userId}/sessions/{sessionId} revokes one session; DELETE /api/users/{userId}/sessions/revoke-all revokes all sessions everywhere).
GET /api/users/{userId}/tenant-ownership Inspects which Tenants a user owns or belongs to before account deletion or transfer.
GET / POST /api/roles Lists or creates RBAC Roles in the current tenant (PUT /api/roles/{id} and DELETE /api/roles/{id} modify or remove roles).
GET / PUT /api/roles/{roleId}/applications/{appId}/menu-access Retrieves or updates granular CRUD permissions (view, add, update, delete) across an Application's hierarchical App Pages tree for a Role.
GET / PUT /api/roles/{roleId}/applications/{appId}/api-access Retrieves or updates which backend Application API endpoints (GET, POST, PUT, DELETE) a Role is permitted to invoke.
GET / POST /api/roles/{roleId}/applications/{appId}/users Lists or assigns users to a Role within the context of a specific Application.
GET / POST /api/groups Lists or creates User Groups (PUT /api/groups/{id}, DELETE /api/groups/{id}).
POST / DELETE /api/groups/{id}/applications/{applicationId} Grants or revokes an entire Group's access to an Application.
POST / DELETE /api/groups/{id}/users Adds or removes users (DELETE /api/groups/{id}/users/{userId}) from a Group.

7. B2B Organizations & Organization Units (Core.SSO.Id)

Method Endpoint Path Description
GET / POST /api/organizations Lists or creates B2B Customer Organizations (Tier 3 of the 4-Tier Policy Cascade).
GET / PUT / DELETE /api/organizations/{id} Gets, updates, or deletes an Organization, including its override flags (overrideGeneral, overrideBranding, overrideSecurity, overrideTokens, overrideMfa).
GET / POST / DELETE /api/organizations/{id}/connections Manages organization-specific SSO Connections (including assignToOrganizationOnly connections dedicated to a single enterprise customer).
GET / PUT /api/organizations/{id}/factors Configures MFA factors enforced specifically for members of this Organization.
GET / POST /api/organizations/{organizationId}/users Lists or assigns users (and their Application Roles) within an Organization.
GET / POST /api/organization-units Lists or creates hierarchical Organization Units / Sub-Departments (Tier 4 of the 4-Tier Cascade). Also supports PUT /api/organization-units/{id}, DELETE /api/organization-units/{id}, and nested /connections, /groups, /factors, and /users sub-resources.

8. Tenant Settings, 1-Click Custom Domains, Members & Stripe Billing

Method Endpoint Path Description
GET / PUT /api/settings/tenant Retrieves or saves the comprehensive Tenant Settings payload (General, Branding, Password Policy, Session Policy, Token Settings, Threat Detection, IP/Country Geofencing, Compliance, and Governance).
POST /api/settings/tenant/detect-dns-provider Inspects NS/SOA records for a custom domain (e.g., login.yourcompany.com) to automatically detect Cloudflare, GoDaddy, Hostinger, or Namecheap.
POST /api/settings/tenant/auto-connect/{provider} 1-Click Automated DNS CNAME & SSL provisioning for cloudflare, godaddy, hostinger, or namecheap.
POST /api/settings/tenant/verify-domain Verifies DNS CNAME propagation and provisions the managed TLS certificate for the tenant's custom domain.
GET / PUT /api/settings/tenant/email-templates Retrieves or customizes transactional HTML email templates (Welcome, Invite, Password Reset, Email Verification, MFA OTP, Security Alert).
POST /api/settings/tenant/smtp Configures or tests custom SMTP relay credentials (also managed via /api/smtp and /api/smtp/test).
POST /api/settings/tenant/governance/support-token Generates a time-bound, auditable Support Access Delegation Token for temporary vendor troubleshooting.
POST /api/tenant-management Creates a new isolated Tenant workspace (with dedicated database schema migration via POST /api/tenant-management/{tenantSlug}/migrate).
GET / POST /api/tenants/{tenantId}/members Lists or invites administrative Tenant Members (POST /api/tenants/{tenantId}/members/invite).
GET / POST /api/tenants/{tenantId}/roles Lists or creates administrative Tenant Roles with menu-level access control (PUT /api/tenants/{tenantId}/roles/{roleId}/menus).
GET /api/stripe/usage-summary Returns current tenant resource consumption vs plan quotas (MAUs, Applications, Organizations, Connections).
POST /api/stripe/create-checkout-session Creates a Stripe Checkout session for upgrading to Growth, Business, or Enterprise service plans.

9. Tamper-Evident Audit Logs, SIEM, Compliance & Analytics

Method Endpoint Path Description
GET /api/audit-logs Queries immutable administrative and authentication audit logs with filtering by actor, entity, action, status, IP, and date range.
GET /api/audit-logs/{id} Retrieves full audit record including before/after JSON state diff and SHA-256 hash chain signature.
GET /api/audit-logs/verify-integrity Cryptographically verifies the SHA-256 tamper-evident hash chain across stored audit log entries to prove zero log manipulation for SOC 2 / ISO 27001 auditors.
GET /api/audit-logs/export-siem Exports audit events formatted for SIEM ingestion (generic_json, splunk_hec, datadog, aws_cloudwatch).
GET /api/compliance/readiness-report Evaluates tenant security settings against GDPR, HIPAA, SOC 2, and ISO 27001 controls and returns a live readiness score.
POST /api/compliance/apply-preset One-click application of regulatory security baselines (gdpr, hipaa, soc2, iso27001).
GET /api/compliance/export-my-data GDPR Article 15 / 20 Right to Access & Data Portability JSON export for the authenticated user (DELETE /api/compliance/delete-my-account executes GDPR Article 17 Right to Erasure).
GET /api/analytics/dashboard-stats Executive telemetry summary (also see /api/analytics/login-trends, /mfa-statistics, /user-growth, /authentication-stats, /compliance-metrics, /top-applications).
AI Agent Prompt Generate a Typed SSO.ID v2 Management API SDK Client 
You are an expert SDK architect. Build a strongly-typed **SSO.ID v2 Management API Client (`SsoIdManagementClient`)** targeting `https://{your-tenant}.sso.id/api`.

### Requirements
1. **Authentication & Headers**:
   - Accept `{ baseUrl: 'https://{your-tenant}.sso.id/api', tenantId: string, region?: 'US' | 'EU', accessTokenProvider: () => Promise }`.
   - Automatically inject `Authorization: Bearer `, `X-Tenant-Id: `, and `X-Region: ` on every request.
2. **Resource Modules to Generate**:
   - `applications`: `list()`, `get(id)`, `create(payload)`, `update(id, payload)`, `delete(id)`, `getMenus(id)`, `getApis(id)`, `getConnections(id)`, `getFactors(id)`
   - `connections`: `list()`, `getDefaults()`, `create(payload)`, `testLiveConnection(payload)`, `checkHealth(id)`
   - `users`: `list(params)`, `invite(payload)`, `getSessions(userId)`, `revokeAllSessions(userId)`
   - `roles`: `list()`, `create(payload)`, `setMenuAccess(roleId, appId, permissions)`, `setApiAccess(roleId, appId, apiIds)`
   - `organizations`: `list()`, `create(payload)`, `update(id, payload)`, `assignConnection(orgId, connectionId)`
   - `scim`: `listUsers(filter)`, `provisionUser(scimUser)`, `deactivateUser(userId)`
   - `auditLogs`: `query(filters)`, `verifyIntegrity()`, `exportSiem(format)`
3. Include automatic exponential backoff on `429 Too Many Requests` and typed error classes.