SCIM 2.0 Provisioning

Automate user and group lifecycle management with SCIM 2.0 (System for Cross-domain Identity Management). When connected, your identity provider automatically creates, updates, and deactivates Flowstate user accounts as people join, change roles, or leave your organization.

Overview

Without SCIM, administrators must manually create and deactivate user accounts in Flowstate. With SCIM provisioning enabled:

• New hires get a Flowstate account automatically when they are assigned the application in your IdP
• Attribute changes (name, email, group membership) sync automatically
• Departures are deactivated in Flowstate when unassigned or deactivated in the IdP
• Group membership changes update Flowstate roles in real time

Base URL

All SCIM requests use your tenant-specific base URL:

https://{tenant}.flowstate.inc/api/scim/v2

Replace {tenant} with your tenant subdomain (e.g., acme.flowstate.inc).

Step 1: Create a SCIM Bearer Token

SCIM requests authenticate with a bearer token. To create one:

1. Navigate to Settings > Authentication > SCIM Provisioning
2. Click Generate Token
3. Enter a descriptive name (e.g., "Okta SCIM Token")
4. Copy the token immediately -- it is shown only once

scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6

WARNING

Store the SCIM token securely. If you lose it, you must revoke the old token and generate a new one. Revoking a token immediately breaks all provisioning from the IdP until you configure the new token.

Step 2: Configure Your Identity Provider

Enter the following values in your IdP's SCIM provisioning settings:

Field	Value
Base URL	https://your-tenant.flowstate.inc/api/scim/v2
Auth Type	Bearer Token (OAuth Bearer Token)
Bearer Token	The token from Step 1

See the IdP-specific setup guides below for detailed instructions for Okta, Azure AD/Entra ID, and OneLogin.

Endpoints Reference

Flowstate implements the following SCIM 2.0 endpoints:

Users

Method	Path	Description
GET	/Users	List users (paginated)
GET	/Users/{id}	Get a single user
POST	/Users	Create a new user
PUT	/Users/{id}	Replace a user
PATCH	/Users/{id}	Update specific fields
DELETE	/Users/{id}	Deactivate a user

Create User Request

curl -X POST "https://your-tenant.flowstate.inc/api/scim/v2/Users" \
  -H "Authorization: Bearer scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane.chen@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Chen"
    },
    "emails": [
      {
        "primary": true,
        "value": "jane.chen@acme.com",
        "type": "work"
      }
    ],
    "active": true
  }'

Create User Response

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "clx1a2b3c4d5e6f7g8h9",
  "userName": "jane.chen@acme.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Chen"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane.chen@acme.com",
      "type": "work"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-03-11T10:30:00Z",
    "lastModified": "2026-03-11T10:30:00Z",
    "location": "https://acme.flowstate.inc/api/scim/v2/Users/clx1a2b3c4d5e6f7g8h9"
  }
}

Deactivate User (PATCH)

curl -X PATCH "https://your-tenant.flowstate.inc/api/scim/v2/Users/clx1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

List Users with Filter

curl -X GET "https://your-tenant.flowstate.inc/api/scim/v2/Users?filter=userName%20eq%20%22jane.chen%40acme.com%22&count=20&startIndex=1" \
  -H "Authorization: Bearer scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"

Groups

Method	Path	Description
GET	/Groups	List groups (paginated)
GET	/Groups/{id}	Get a single group
POST	/Groups	Create a new group
PUT	/Groups/{id}	Replace a group
PATCH	/Groups/{id}	Update group membership
DELETE	/Groups/{id}	Delete a group

Create Group Request

curl -X POST "https://your-tenant.flowstate.inc/api/scim/v2/Groups" \
  -H "Authorization: Bearer scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Flowstate-Admins",
    "members": [
      {
        "value": "clx1a2b3c4d5e6f7g8h9",
        "display": "jane.chen@acme.com"
      }
    ]
  }'

Update Group Membership (PATCH)

curl -X PATCH "https://your-tenant.flowstate.inc/api/scim/v2/Groups/clx9g8r7o6u5p4" \
  -H "Authorization: Bearer scim_t1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          {
            "value": "clx7n8m9k0j1h2g3",
            "display": "alex.rivera@acme.com"
          }
        ]
      }
    ]
  }'

Discovery Endpoints

These read-only endpoints allow your IdP to discover Flowstate's SCIM capabilities:

Method	Path	Description
GET	/ServiceProviderConfig	SCIM capabilities and features
GET	/Schemas	Supported SCIM schemas
GET	/ResourceTypes	Supported resource types

ServiceProviderConfig Response

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch": { "supported": true },
  "bulk": { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
  "filter": { "supported": true, "maxResults": 200 },
  "changePassword": { "supported": false },
  "sort": { "supported": false },
  "etag": { "supported": false },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "OAuth Bearer Token",
      "description": "Authentication scheme using a bearer token"
    }
  ]
}

User Provisioning Flow

The typical provisioning lifecycle works as follows:

1. Assignment -- An admin assigns a user to the Flowstate application in the IdP
2. Create -- The IdP sends a POST /Users request to Flowstate, creating the user account
3. Attribute sync -- When user attributes change in the IdP, it sends a PUT or PATCH /Users/{id} request
4. Group sync -- When group membership changes, the IdP sends PATCH /Groups/{id} to update members
5. Deprovisioning -- When a user is unassigned or deactivated in the IdP, it sends a PATCH /Users/{id} to set active: false, or a DELETE /Users/{id}

Group-to-Role Mapping

SCIM groups map to Flowstate roles. When your IdP provisions a group and assigns members, Flowstate automatically updates the corresponding users' roles.

Configure group-to-role mappings in Settings > Authentication > Auth Providers on the SAML or OAuth provider linked to the same domain. The SCIM group names must match the group names in your role mappings.

SCIM Group Name	Flowstate Role	Effect
Flowstate-Admins	Admin	Full access including settings
Flowstate-Editors	Editor	Create and modify plans and data
Flowstate-Viewers	Viewer	Read-only access to plans and data

IdP-Specific Setup Guides

Okta

1. In the Okta admin console, go to Applications > Applications
2. Click Browse App Catalog and search for "SCIM 2.0 Test App (Header Auth)" -- or create a new SWA app and enable SCIM provisioning
3. Under the Provisioning tab, click Configure API Integration
4. Check Enable API integration
5. Set Base URL to https://your-tenant.flowstate.inc/api/scim/v2
6. Set API Token to the bearer token from Step 1
7. Click Test API Credentials to verify connectivity
8. Click Save
9. Under Provisioning > To App, enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
10. Assign users and groups to the application

TIP

Okta sends a GET /Users?filter=userName eq "..." request when testing credentials. If the test succeeds, your SCIM integration is working.

Azure AD / Entra ID

1. In the Azure portal, go to Enterprise Applications
2. Click New application > Create your own application
3. Name it "Flowstate" and select Integrate any other application you don't find in the gallery
4. Go to Provisioning and set the mode to Automatic
5. Under Admin Credentials:
   • Set Tenant URL to https://your-tenant.flowstate.inc/api/scim/v2
   • Set Secret Token to the bearer token from Step 1
6. Click Test Connection to verify
7. Click Save
8. Under Mappings, configure attribute mappings:
   • userPrincipalName -> userName
   • givenName -> name.givenName
   • surname -> name.familyName
   • mail -> emails[type eq "work"].value
9. Set the provisioning scope and start provisioning

WARNING

Azure AD/Entra ID uses a 40-minute provisioning cycle by default. Initial provisioning of all users may take longer depending on the size of your directory. You can trigger an on-demand provisioning cycle for individual users.

OneLogin

1. In the OneLogin admin portal, go to Applications > Applications
2. Click Add App and search for "SCIM Provisioner with SAML (SCIM v2 Core)"
3. Under Configuration:
   • Set SCIM Base URL to https://your-tenant.flowstate.inc/api/scim/v2
   • Set SCIM Bearer Token to the token from Step 1
4. Under Provisioning, enable:
   • Create user
   • Delete user
   • Update user
5. Under Users, assign users to the application
6. Click Save

Error Responses

SCIM endpoints return standard SCIM error responses:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "User with userName 'jane.chen@acme.com' already exists.",
  "status": "409"
}

Status	Meaning
400	Invalid request body or missing required fields
401	Invalid or missing bearer token
404	User or group not found
409	Conflict (e.g., duplicate userName)
500	Internal server error