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, Microsoft Entra ID or OneLogin) and it creates and deactivates users in your Cirrux workspace for you.

SCIM is not self-serve yet: there is no SCIM screen in the workspace admin app. Email help@cirrux.info and we issue a token and set the default domain for your workspace with you. Only users are supported; groups are not.

Getting started

Authentication

SCIM requests are authenticated with a bearer token that we issue for your workspace. We only store a hash of it, so it can be shown once and never retrieved again: put it straight into your identity provider. If it is lost, we revoke it and issue a new one.

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.info/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

Method	Path	Description
GET	`/Users`	List and filter users (up to 100 per page)
GET	`/Users/:id`	Get a single user
POST	`/Users`	Create (provision) a user
PUT	`/Users/:id`	Update name, externalId and active
PATCH	`/Users/:id`	Partial update (e.g. deactivate)
DELETE	`/Users/:id`	Deactivate a user (same as active: false)
GET	`/ServiceProviderConfig`	SCIM service provider configuration
GET	`/Schemas`	Supported SCIM schemas
GET	`/ResourceTypes`	Supported resource types

User schema

The following SCIM User attributes are mapped to Cirrux:

SCIM attribute	Cirrux field	Notes
`id`	Membership UUID	Read-only, assigned by Cirrux
`externalId`	External ID	Your IDP's identifier for the user
`userName`	Primary email address	Used for the new address when it is at the default domain
`name.givenName`	First name
`name.familyName`	Last name
`emails[0].value`	Primary email address	Checked before userName; also used as the recovery address
`active`	Membership status	false deactivates the user and mailbox

Provisioning lifecycle

Creating a user

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

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

Every new mailbox is created at the workspace’s default domain, which we set for you during setup. The part before the @ comes from emails[0].value or userName when that address is at the default domain, and otherwise from the name (first.last). If that address is already taken, the request fails with a 409.

Deactivating and reactivating

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

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

When a user is reactivated (active: true), they get a new, empty mailbox at the default domain, with an address built from their name (first.last). Their previous mailbox is not restored automatically, so reactivation never quietly gives someone back access to old 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 (same as userName)

Only a single eq comparison is supported. Pagination uses the startIndex and count query parameters, with at most 100 results per page.

Identity provider setup

Okta

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

Microsoft Entra ID (Azure AD)

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