SCIM-Based User Provisioning

Overview

Use the Workvivo SCIM API to automate user onboarding and offboarding by connecting your identity provider (IdP) directly to Workvivo, ensuring your employee directory is always in sync without manual intervention.

Managing user accounts manually across enterprise platforms doesn't scale. When employees join, move between departments, or leave the organisation, their Workvivo access needs to reflect those changes immediately - not days later when someone remembers to update a spreadsheet. Workvivo's SCIM 2.0 implementation lets your identity provider (Okta, Microsoft Entra ID, or a direct SCIM client) push user lifecycle changes directly to Workvivo in real time.

When a new hire is added to your IdP, they're automatically provisioned in Workvivo with the correct profile attributes. When someone leaves, their access is revoked instantly. Department changes, title updates, and manager reassignments flow through automatically - keeping your Workvivo directory accurate without anyone touching the admin panel.

For organisations that need to go beyond standard SCIM provisioning - such as verifying synced users, managing team memberships programmatically, or controlling frontline access based on external workforce data - the Workvivo API provides complementary endpoints that extend your provisioning workflows.

Value & Benefits

Eliminate manual user administration. New hires appear in Workvivo automatically the moment they're added to your IdP. No tickets, no waiting, no forgotten accounts.

Ensure instant offboarding. When an employee is deactivated in your IdP, their Workvivo access is revoked immediately - closing the security gap between HR action and platform access removal.

Keep profile data accurate at all times. Job titles, departments, managers, and contact details sync continuously from your source of truth. Employees never need to manually update their Workvivo profile.

Reduce IT operational burden. Provisioning and deprovisioning happen without IT intervention. For organisations with thousands of employees, this eliminates hundreds of hours of manual account management per year.

Support complex workforce structures. Combine SCIM provisioning with the Workvivo API to automate team assignments, space memberships, and frontline access control - building a fully automated user lifecycle pipeline.

Applications

Automated new hire onboarding. When HR adds a new employee to your IdP (e.g., Okta or Microsoft Entra ID), SCIM automatically provisions their Workvivo account with correct name, email, job title, department, location, and manager - ready for day one.

Real-time offboarding and access revocation. Deactivating a user in your IdP immediately deactivates their Workvivo account via SCIM, ensuring former employees lose access without manual intervention or delays.

Continuous profile synchronisation. Department transfers, promotions, manager changes, and contact detail updates in your HR system propagate through your IdP to Workvivo automatically - keeping the employee directory accurate.

Frontline workforce access control. Combine SCIM provisioning with the Frontline Status API to dynamically grant or revoke Workvivo access for shift-based workers based on employment status changes flowing from your workforce management system.

Post-provisioning team assignment. SCIM can map department and location attributes to Workvivo teams. After SCIM creates user accounts, use the API to programmatically assign users to additional Workvivo teams and spaces based on attributes that are not part of your standard SCIM mappings.

Provisioning validation and audit. Use API user lookup endpoints to verify that SCIM-provisioned users exist with the correct attributes, supporting compliance audits and sync health monitoring.

Technical Details

Workvivo supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user provisioning. Your identity provider connects to a SCIM endpoint on your Workvivo tenant domain and pushes user lifecycle events directly. Visit the API reference for the complementary API endpoints used alongside SCIM.

SCIM Access Configuration

SCIM requests use a tenant-specific Workvivo domain and authenticate with a SCIM secret sent as a bearer token. Configure the SCIM secret and provider from Admin > Provisioning > Provisioning Settings.

API bearer tokens do not authenticate SCIM requests.

SCIM Endpoint Formats

Use the endpoint format that matches your provisioning provider:

Provider	Base URL
Direct SCIM API	`https://{your-workvivo-domain}/scim/v2/scim`
Microsoft Entra ID	`https://{your-workvivo-domain}/azure/v2/scim`
Okta	`https://{your-workvivo-domain}/okta/v2/scim`

For direct SCIM calls, create users with POST /Users, replace a user with PUT /Users/{id}, update selected attributes with PATCH /Users/{id}, and deactivate users by setting active to false.

curl -X PATCH https://yourcompany.workvivo.com/scim/v2/scim/Users/662096 \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "externalId": "emp-4521",
    "userName": "jane.doe@company.com",
    "displayName": "Jane Doe",
    "name": {
        "givenName": "Jane",
        "familyName": "Doe"
    },
    "emails": [
        {
            "type": "work",
            "value": "jane.doe@company.com",
            "primary": true
        }
    ],
    "title": "Senior Engineer",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Engineering",
        "manager": {
            "value": "1001"
        }
    }
}

For direct SCIM and Microsoft Entra ID endpoints, manager.value should be the manager's Workvivo user ID. The Okta endpoint accepts the manager's email address.

API: Verify a Provisioned User

Customer API requests use different credentials from SCIM. Complete Quick Start to create an app and API key and find your Base URL and Workvivo-Id before using the following complementary API examples.

After SCIM provisioning, use the API to confirm the user exists with correct attributes:

curl -X GET https://api.workvivo.com/v1/users/by-external-id/emp-4521 \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": {
        "id": 1042,
        "external_id": "emp-4521",
        "email": "jane.doe@company.com",
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "display_name": "Jane Doe",
        "avatar_url": "https://yourcompany.workvivo.com/img/users/1042.jpg",
        "job_title": "Senior Engineer",
        "timezone": "Europe/Dublin",
        "locale": "en-US",
        "hire_date": null,
        "manager_id": 1001,
        "date_of_birth": null,
        "mobile_phone": null,
        "direct_dial": null,
        "has_logged_in": false,
        "created_at": "2026-06-17T09:00:00Z",
        "permalink": "https://yourcompany.workvivo.com/people/1042"
    },
    "status": "success",
    "meta": {}
}

API: Assign User to a Team Post-Provisioning

Once a user is provisioned via SCIM, assign them to any additional teams that are not already managed by your SCIM department or location mappings:

curl -X PATCH https://api.workvivo.com/v1/teams/{team_id}/users \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -F "ids_to_add[]=1042"

{
    "data": {
        "id": 101,
        "external_id": null,
        "name": "Engineering",
        "avatar_url": "https://yourcompany.workvivo.com/img/teams/engineering.jpg",
        "permalink": "https://yourcompany.workvivo.com/directory/teams/101",
        "team_type": {
            "id": 2,
            "name": "Departments"
        }
    },
    "status": "success",
    "meta": {
        "users_added": 1,
        "users_removed": 0
    }
}

API: Update Frontline Access

For shift-based workers provisioned via SCIM, control their Workvivo access dynamically:

curl -X PUT https://api.workvivo.com/v1/users/frontline-status \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "external_id": "emp-4521",
        "is_frontline": true,
        "has_access": true
      }
    ]
  }'

{
    "data": [
        {
            "id": 662096,
            "external_id": "emp-4521",
            "email": "jane.doe@company.com",
            "name": "Jane Doe",
            "is_frontline": true,
            "has_access": true,
            "permalink": "https://yourcompany.workvivo.com/people/662096"
        }
    ],
    "status": "success",
    "meta": {}
}

JavaScript Integration Example

After your identity provider provisions a user through SCIM, verify that the user is available through the Workvivo API and add them to an additional team using their external ID.

const apiUrl = 'https://api.workvivo.com/v1';
const headers = {
    Authorization: `Bearer ${process.env.WORKVIVO_TOKEN}`,
    'Workvivo-Id': process.env.WORKVIVO_ORG_ID,
    Accept: 'application/json',
};

export async function completeProvisioning(userExternalId, teamExternalId) {
    const user = await getUserByExternalId(userExternalId);

    if (!user) {
        // The SCIM operation may not have completed yet. Retry from your job system.
        return { status: 'waiting_for_scim' };
    }

    await addUserToTeam(userExternalId, teamExternalId);

    return { status: 'complete', user };
}

async function getUserByExternalId(externalId) {
    const response = await fetch(
        `${apiUrl}/users/by-external-id/${encodeURIComponent(externalId)}`,
        { headers },
    );

    if (response.status === 404) {
        return null;
    }
    if (!response.ok) {
        throw new Error(`User lookup failed: ${response.status}`);
    }

    return (await response.json()).data;
}

async function addUserToTeam(userExternalId, teamExternalId) {
    const body = new URLSearchParams({
        'external_ids_to_add[0]': userExternalId,
    });
    const response = await fetch(
        `${apiUrl}/teams/by-external-id/${encodeURIComponent(teamExternalId)}/users`,
        {
            method: 'PATCH',
            headers: {
                ...headers,
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            body,
        },
    );

    if (!response.ok) {
        throw new Error(`Team assignment failed: ${response.status}`);
    }
}