SSO & SCIM API

Configure single sign-on (OIDC), manage SCIM bearer tokens for automated user provisioning, and control audit log retention policies. SSO configuration requires OWNER role. SCIM endpoints use bearer token authentication instead of session cookies.

SSO Configuration

Method	Path	Auth	Description
`GET`	`/api/organizations/[orgId]/sso`	OWNER / ADMIN	Get SSO configuration
`PUT`	`/api/organizations/[orgId]/sso`	OWNER only	Create or update SSO configuration
`DELETE`	`/api/organizations/[orgId]/sso`	OWNER only	Delete SSO configuration

SSO Config Request Body (PUT)

Parameter	Type	Required	Description
`provider`	string	Yes	SSO provider type (currently `OIDC`)
`issuerUrl`	string	Yes	OIDC issuer URL (must support `.well-known/openid-configuration`)
`clientId`	string	Yes	OAuth 2.0 client ID from the identity provider
`clientSecret`	string	Yes	OAuth 2.0 client secret (stored encrypted, masked in GET responses)
`allowedDomains`	string[]	Yes	Email domains that can authenticate via this SSO config
`autoProvision`	boolean	No	Auto-create user accounts on first SSO login (default: `true`)
`defaultRole`	string	No	Role for auto-provisioned users: `MEMBER`, `ADMIN` (default: MEMBER)
`enforceSSO`	boolean	No	Block password login for users with matching email domains (default: `false`)

Example: SSO Config Request Body

{
  "provider": "OIDC",
  "issuerUrl": "https://login.microsoftonline.com/tenant-id/v2.0",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "clientSecret": "your-client-secret",
  "allowedDomains": ["acme.com"],
  "autoProvision": true,
  "defaultRole": "MEMBER",
  "enforceSSO": false
}

Example: SSO Config Response (GET)

{
  "id": "cm_sso_abc123",
  "organizationId": "cm_org_ghi789",
  "provider": "OIDC",
  "issuerUrl": "https://login.microsoftonline.com/tenant-id/v2.0",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "clientSecret": "••••••••",
  "allowedDomains": ["acme.com", "acme.co.uk"],
  "autoProvision": true,
  "defaultRole": "MEMBER",
  "enforceSSO": false,
  "createdAt": "2026-02-15T09:00:00.000Z",
  "updatedAt": "2026-03-01T14:22:00.000Z"
}

SCIM Token Management

Method	Path	Auth	Description
`POST`	`/api/organizations/[orgId]/sso/scim-tokens`	OWNER only	Create a SCIM bearer token
`DELETE`	`/api/organizations/[orgId]/sso/scim-tokens/[tokenId]`	OWNER only	Revoke a SCIM token

Example: SCIM Token Creation Response

The token value is only returned once at creation time. Store it securely in your identity provider.

{
  "id": "cm_scimtok_xyz789",
  "label": "Okta SCIM Integration",
  "token": "scim_live_a1b2c3d4e5f6g7h8i9j0...",
  "expiresAt": "2027-03-06T00:00:00.000Z",
  "createdAt": "2026-03-06T10:15:00.000Z"
}

Method	Path	Auth	Description
`POST`	`/api/auth/sso/lookup`	Public	Check if an email domain has SSO configured
`GET`	`/api/auth/sso/callback`	Public	OIDC authorization code callback (redirects to app)

SCIM 2.0 User Provisioning

SCIM endpoints use bearer token authentication (via the tokens created above), not session cookies. Pass the token in the Authorization: Bearer scim_live_... header.

Method	Path	Description
`GET`	`/api/scim/v2/Users`	List provisioned users
`POST`	`/api/scim/v2/Users`	Provision a new user
`GET`	`/api/scim/v2/Users/[userId]`	Get a specific user
`PATCH`	`/api/scim/v2/Users/[userId]`	Deactivate or update a user
`DELETE`	`/api/scim/v2/Users/[userId]`	Deprovision (hard delete) a user

SCIM List Query Parameters

Parameter	Type	Default	Description
`startIndex`	number	1	1-based pagination index
`count`	number	20	Records per page (1-100)
`filter`	string	-	SCIM filter expression (e.g. `userName eq "jane@acme.com"`)

Example: SCIM User List Response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "cm_user_abc123",
      "externalId": "00u1a2b3c4d5e6f7g8",
      "userName": "jane.doe@acme.com",
      "name": {
        "givenName": "Jane",
        "familyName": "Doe"
      },
      "emails": [
        {
          "value": "jane.doe@acme.com",
          "primary": true
        }
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2026-02-20T08:00:00.000Z",
        "lastModified": "2026-03-01T12:30:00.000Z"
      }
    }
  ]
}

Audit Retention

Method	Path	Auth	Description
`GET`	`/api/organizations/[orgId]/audit-retention`	ADMIN / OWNER	Get audit log retention configuration
`PUT`	`/api/organizations/[orgId]/audit-retention`	ADMIN / OWNER	Update audit log retention configuration

Retention Config Parameters (PUT)

Parameter	Type	Default	Description
`retentionDays`	number	365	Days to retain audit log entries before deletion
`archiveAfterDays`	number	90	Days after which entries are moved to cold storage
`autoDelete`	boolean	false	Automatically delete entries beyond the retention period

Example: Retention Config Response

{
  "organizationId": "cm_org_ghi789",
  "retentionDays": 365,
  "archiveAfterDays": 90,
  "autoDelete": false,
  "updatedAt": "2026-03-01T14:00:00.000Z"
}

Notes

SSO configuration changes are recorded in the audit log with action UPDATE and resource SSO_CONFIG.
The clientSecret is encrypted at rest and masked in GET responses (returns "••••••••").
SCIM bearer tokens are shown in full only once at creation. They cannot be retrieved again after the initial response.
SCIM endpoints follow the RFC 7644 specification for user provisioning and deprovisioning.
When enforceSSO is enabled, users with matching email domains can only log in through the configured identity provider.
The SSO lookup endpoint is rate-limited to prevent email enumeration attacks.
Audit retention changes take effect on the next scheduled cleanup job (runs daily at 02:00 UTC).