cirrux

SCIM 2.0 Provisioning

Cirrux supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user provisioning and deprovisioning. Connect your identity provider — such as Okta, Azure AD, or OneLogin — to automatically manage users in your Cirrux workspace.

Getting started

Authentication

SCIM requests are authenticated using bearer tokens. Generate a token from the Cirrux admin panel under your workspace settings. The token is shown once at creation — store it securely in your identity provider.

Include the token in every request as an Authorization header:

Authorization: Bearer your-scim-token

Base URL

All SCIM endpoints are available under:

https://api.cirrux.co/scim/v2

Make sure your identity provider is configured with this base URL. All request and response bodies use the application/scim+json content type.

Endpoints

API reference

MethodPathDescription
GET/UsersList and filter users
GET/Users/:idGet a single user
POST/UsersCreate (provision) a user
PUT/Users/:idReplace a user
PATCH/Users/:idPartial update (e.g. deactivate)
DELETE/Users/:idDelete a user
GET/ServiceProviderConfigSCIM service provider configuration
GET/SchemasSupported SCIM schemas
GET/ResourceTypesSupported resource types

User schema

The following SCIM User attributes are mapped to Cirrux:

SCIM attributeCirrux fieldNotes
idMembership UUIDRead-only, assigned by Cirrux
externalIdExternal IDYour IDP's identifier for the user
userNamePrimary email addressMust be an email at a verified domain
name.givenNameFirst name
name.familyNameLast name
emails[0].valuePrimary email addressSame as userName
activeMembership statusfalse deactivates the user and mailbox

Provisioning lifecycle

Creating a user

When your identity provider sends a POST /Users request, Cirrux will:

  1. Create a new user account with the provided name
  2. Create a mailbox with an email address at your workspace’s default SCIM domain
  3. Add the user as a member of your workspace
  4. Store the external ID for future correlation

The default SCIM domain determines which domain is used for new mailbox addresses. Configure this in the admin panel under your workspace settings before provisioning users.

Deactivating and reactivating

When your identity provider deactivates a user (typically via PATCH /Users/:id with active: false), Cirrux will:

  1. Deactivate the user’s workspace membership
  2. Soft-delete their mailbox, which stops billing for that mailbox
  3. Revoke all active sessions

When a user is reactivated (active: true), a new mailbox is created with their email address. Previous mailbox data remains archived and is not automatically restored, ensuring no unintended access to prior messages.

Filtering

The GET /Users endpoint supports SCIM filter syntax for looking up users. Supported filters:

  • userName eq "user@example.com"— find by email address
  • externalId eq "ext-123"— find by external ID
  • emails.value eq "user@example.com"— find by email (alias for userName)

Pagination is supported via startIndex and count query parameters.

Identity provider setup

Okta

  1. In Okta, go to Applications → Create App Integration → SCIM 2.0
  2. Set the SCIM connector base URL to https://api.cirrux.co/scim/v2
  3. Set the unique identifier field to userName
  4. Enable the provisioning actions you need: Create Users, Update User Attributes, Deactivate Users
  5. Under Authentication Mode, select HTTP Header and paste your SCIM bearer token
  6. Test the connection and save

Microsoft Entra ID (Azure AD)

  1. In the Azure portal, go to Enterprise Applications → create a new application
  2. Under Provisioning, set the mode to Automatic
  3. Set the Tenant URL to https://api.cirrux.co/scim/v2
  4. Set the Secret Token to your SCIM bearer token
  5. Test the connection, then configure attribute mappings
  6. Map userPrincipalName to userName, and objectId to externalId
  7. Enable provisioning and set the desired scope
HelpPrivacyTermsSustainability