Atlassian Loom User Management API Guide

Auth method: Not applicable - no open user-management REST API exists. SCIM uses a Bearer token issued via the WorkOS-backed SCIM setup console in Loom Workspace Settings > Security. The recordSDK uses a public App ID (SDK Standard) or JWS key-pair (SDK Custom/Standard advanced).

Setup steps

1. Ensure workspace is on the Loom Enterprise plan.
2. Verify at least one domain in Workspace Settings > Security > Authorize Domains.
3. Configure SAML SSO via the 'Configure SSO' button in the Security tab (SSO must be enabled before SCIM).
4. After SSO is active, open the Security tab and follow the WorkOS setup guide to enable Directory Sync (SCIM).
5. Copy the SCIM Endpoint URL and Bearer Token from the WorkOS setup console - store them securely as they are shown only once.
6. Paste the Endpoint and Bearer Token into your IdP (Okta, Entra ID, Google Workspace, OneLogin) SCIM configuration.
7. Set the unique identifier field for users to 'email' in the IdP SCIM app.
8. Note: SCIM API keys expire after 1 year (policy effective December 2024); rotate annually via Security > Identity providers > Regenerate API key.

Provision (create) user

• Method: POST
• URL: {scim_endpoint}/Users
• Watch out for: The SCIM endpoint URL is workspace-specific and generated by WorkOS during setup. It is not a fixed public URL. Retrieve it from Workspace Settings > Security > Directory Sync.

Request example

POST {scim_endpoint}/Users
Authorization: Bearer <token>
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"jane@example.com",
  "name":{"givenName":"Jane","familyName":"Doe"},
  "active":true
}

Response example

HTTP/1.1 201 Created
{
  "id":"<loom-user-id>",
  "userName":"jane@example.com",
  "active":true
}

Deprovision (deactivate) user

• Method: PATCH
• URL: {scim_endpoint}/Users/{id}
• Watch out for: Deprovisioning behavior (Deactivate vs. Delete) is controlled by the workspace-level 'Member Deprovisioning' setting, not by the SCIM operation alone. Default is Deactivate (content preserved). Without SCIM, users are only deactivated when they next attempt to log in.

Request example

PATCH {scim_endpoint}/Users/{id}
Authorization: Bearer <token>
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:api:messages:2.0:PatchOp"],
  "Operations":[{"op":"replace","path":"active","value":false}]
}

Response example

HTTP/1.1 200 OK
{
  "id":"<loom-user-id>",
  "active":false
}

Update user attributes / role

• Method: PATCH
• URL: {scim_endpoint}/Users/{id}
• Watch out for: loomMemberRole is a custom attribute; it must be mapped in the IdP profile editor. Once set to creator/viewer/admin, the 'default' value is no longer needed.

Request example

PATCH {scim_endpoint}/Users/{id}
Authorization: Bearer <token>
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:api:messages:2.0:PatchOp"],
  "Operations":[{"op":"replace","path":"loomMemberRole","value":"creator"}]
}

Response example

HTTP/1.1 200 OK
{
  "id":"<loom-user-id>",
  "userName":"jane@example.com"
}

List / filter users

• Method: GET
• URL: {scim_endpoint}/Users
• Watch out for: Loom's SCIM is powered by WorkOS. Filtering and pagination behavior follows WorkOS SCIM conventions; no Loom-specific pagination parameters are documented publicly.

Request example

GET {scim_endpoint}/Users
Authorization: Bearer <token>

Response example

HTTP/1.1 200 OK
{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":2,
  "Resources":[{"id":"...","userName":"jane@example.com"}]
}

Get user by ID

• Method: GET
• URL: {scim_endpoint}/Users/{id}
• Watch out for: The {id} is the Loom/WorkOS internal user ID, not the IdP externalId.

Request example

GET {scim_endpoint}/Users/{id}
Authorization: Bearer <token>

Response example

HTTP/1.1 200 OK
{
  "id":"<loom-user-id>",
  "userName":"jane@example.com",
  "active":true
}

Provision group / sync role group

• Method: POST
• URL: {scim_endpoint}/Groups
• Watch out for: Recommended pattern: create three IdP groups (Loom Creators, Loom Viewers, Loom Admins) and assign loomMemberRole per group. Not all IdPs support group-level custom attributes.

Request example

POST {scim_endpoint}/Groups
Authorization: Bearer <token>
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName":"Loom Creators",
  "members":[{"value":"<user-id>"}]
}

Response example

HTTP/1.1 201 Created
{
  "id":"<group-id>",
  "displayName":"Loom Creators"
}

• Rate limits: No publicly documented rate limits for the Loom SCIM endpoint or the recordSDK. Loom does not publish rate limit tiers or headers in official documentation.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No official rate limit data available. The recordSDK enforces usage limits per user account tier (e.g., Starter/Guest: 5-minute max recording, 25 videos), but these are product limits, not API rate limits.

• Pagination method: none

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: Loom does not expose outbound webhooks for user lifecycle events to external consumers. The recordSDK exposes client-side JavaScript events (e.g., recording-complete, upload-complete) within the embedding application, but these are not server-side webhooks for user management.

• Alternative event strategy: Use SCIM push from your IdP (Okta, Entra ID, etc.) to drive real-time user provisioning and deprovisioning into Loom. IdP-side SCIM events are the authoritative trigger mechanism.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (custom pricing). Loom Business and Business+AI plans purchased from Atlassian.com do not include Atlassian Guard; Guard must be purchased separately to enable SSO/SCIM on non-Enterprise plans.

• Endpoint: Workspace-specific URL generated by WorkOS during SCIM setup in Workspace Settings > Security > Directory Sync. Not a fixed public URL. Example pattern: https://auth.workos.com/scim/v2/

• Supported operations: POST /Users - provision user, GET /Users - list users, GET /Users/{id} - get user by ID, PATCH /Users/{id} - update user attributes or deactivate, POST /Groups - create group, GET /Groups - list groups, PATCH /Groups/{id} - update group membership, DELETE /Users/{id} - delete user (if workspace deprovisioning set to Delete)

Limitations:

• SAML SSO must be fully configured before SCIM can be enabled - SSO is a hard prerequisite.
• Enterprise plan required; Business plans from Atlassian.com do not include Guard (SSO/SCIM).
• SCIM API keys expire after 1 year (policy effective December 2024); expiry of key immediately halts all provisioning/deprovisioning until rotated.
• Unique identifier field for users must be set to 'email' when using the same IdP app for both SSO and SCIM to avoid duplicate Atlassian accounts.
• Deprovisioning behavior (Deactivate vs. Delete) is a workspace-level toggle, not controlled per SCIM call - admins must align this setting with their IdP's deprovisioning action.
• Domain capture (auto-join) can create provisioning gaps: users with matching domains may auto-join the Enterprise workspace outside of SCIM control if domain capture is enabled.
• Not all IdPs support group-level custom attributes; loomMemberRole may need to be set per-user rather than per-group in some IdPs.
• SCIM token is shared across IdPs - refreshing it requires updating all connected IdPs simultaneously.
• Google Workspace users receive JIT provisioning only, not full SCIM.
• Default groups in Atlassian cannot be managed via SCIM; only IdP-synced groups are SCIM-manageable.
• Existing users with outside-domain email addresses will be blocked from Loom login once SSO is enabled - must be resolved before SSO activation.

Three operational scenarios cover the majority of SCIM implementation work:

• Onboarding via Okta SCIM: After SSO and SCIM are configured, assign the employee to the Loom Okta app. SCIM pushes POST /Users immediately, provisioning the account without waiting for first login. Map the custom loomMemberRole attribute in Okta's Profile Editor to control workspace role (creator/viewer/admin); this attribute is non-standard and will not map automatically.

• Offboarding with immediate revocation: Set the workspace-level Member Deprovisioning toggle to 'Deactivate' (preserves content) or 'Delete' (removes user and content) before relying on SCIM for offboarding. When the IdP deactivates or unassigns the user, it sends PATCH /Users/{id} with active:false - Loom acts on this immediately. Without SCIM, the account stays live until next login.

• SCIM key rotation: Regenerating the Bearer Token invalidates the old key instantly. If multiple IdPs share the same token - Loom's recommended pattern - all must be updated in the same maintenance window. Retrieve the new endpoint URL and token from the admin console; they are shown only once.

Onboard new employee via Okta SCIM

1. Ensure Loom Enterprise plan is active and SAML SSO is configured in Workspace Settings > Security.
2. In the Loom Security tab, open Directory Sync (SCIM) and follow the WorkOS setup guide to generate the SCIM Endpoint URL and Bearer Token.
3. In Okta admin, configure the SCIM 2.0 app: paste the Endpoint into 'SCIM connector base URL' and the Bearer Token into 'OAuth Bearer Token'. Set unique identifier to 'email'.
4. Map the custom attribute loomMemberRole in Okta's Profile Editor to control the user's Loom role (creator/viewer/admin).
5. Assign the new employee to the Loom Okta app. SCIM pushes a POST /Users to Loom immediately, provisioning the account without waiting for first login.
6. Verify the user appears in Loom Workspace > Members with the correct role.

Watch out for: If the email attribute mapping differs between the SAML SSO config and the SCIM provisioning config in Okta, the user may end up with duplicate Atlassian accounts. Ensure both use the same email field (default: email / UserPrincipalName).

Offboard departing employee (immediate access revocation)

1. Confirm Workspace Settings > Security > Member Deprovisioning is set to 'Deactivate' (default, preserves video content) or 'Delete' (removes user and content - use with caution).
2. In the IdP (e.g., Okta or Entra ID), deactivate or unassign the user from the Loom application.
3. The IdP sends a SCIM PATCH /Users/{id} with active:false to the Loom SCIM endpoint.
4. Loom immediately deactivates the user (or deletes, per workspace setting) without waiting for their next login attempt.
5. Confirm the user no longer appears as active in Loom Workspace > Members.

Watch out for: Without SCIM, users are only deactivated when they next attempt to log in - a significant security gap for departing employees with access to recorded video content. SSO alone does not solve this.

Rotate expiring SCIM API key before provisioning outage

1. Log in to admin.atlassian.com (or Loom Workspace Settings > Security for legacy workspaces).
2. Navigate to Security > Identity providers > [your IdP directory] > Provisioning to view the API key expiration date.
3. Before expiry, click 'Regenerate API key'. Copy the new SCIM base URL and API key - these are shown only once.
4. Update the Bearer Token in every IdP (Okta, Entra ID, etc.) that uses this SCIM connection. The old key stops working immediately upon regeneration.
5. Test provisioning by assigning a test user in the IdP and confirming they appear in Loom.

Watch out for: Regenerating the key immediately invalidates the old key. If multiple IdPs share the same SCIM token (Loom recommends reusing the token across IdPs), all must be updated in the same maintenance window to avoid provisioning failures.

The most consequential caveat is the deprovisioning gap: without SCIM, users are only deactivated on their next login attempt, not at the moment of offboarding. For a tool that stores recorded video content, this is a meaningful access-hygiene risk that SSO alone does not resolve.

Several implementation details compound this. The loomMemberRole custom attribute must be explicitly mapped in the IdP profile editor - it is not a standard SCIM field and will be silently ignored if unmapped.

Domain capture is enabled by default and can cause users to auto-join the Enterprise workspace outside of SCIM control, creating unmanaged accounts that bypass the provisioning flow entirely.

Google Workspace users receive JIT provisioning only, not full SCIM, which limits lifecycle automation for Google-first organizations. Additionally, Business and Business+AI plans purchased through Atlassian.com do not include Atlassian Guard - Guard must be purchased separately to enable SSO and SCIM on those plans, a cost that is not surfaced prominently at purchase.