Okta User Provisioning

The Firstup create user API allows you to integrate with SCIM-compliant providers. This SCIM-compliant data sync allows you to create one user record across multiple applications.

Create your single-user record in an external SCIM-compliant application, and sync with our API to create a Firstup user record with the same execution.

Firstup supports Just-in-Time (JIT). If your SCIM-compliant provider (e.g. an IDP like Okta) authenticates a user successfully, but they don't yet have a user account with us, Firstup automatically creates a registered user for the Employee Experience.

Review how our Create User API works before integrating.

Use Okta lifecycle management to create, update, deactivate, and reactivate users in a Firstup program through the Firstup SCIM 2.0 User Management API.

In this configuration, Okta is the source and Firstup is the target. Assigning a person to the Okta app provisions that person in Firstup. This guide does not cover importing Firstup users into Okta or configuring SSO.

Review how the Create User API works before integrating.

You need:

• Administrator access to your Okta organization
• A Firstup program
• The region-specific Firstup SCIM base URL
• A long-lived bearer token supplied by Firstup with users.read and users.write access
• One or more users in Okta.

Region-specific SCIM base URLs

Use the Partner API URL for the program's region. Do not use an authentication host as the SCIM connector base URL. The authentication hosts (auth.socialchorus.com, auth.us2.onfirstup.com, auth.onfirstup.eu) issue tokens only and do not serve SCIM endpoints.

Okta navigation varies by organization and interface version. Add or create a SCIM 2.0 app integration that supports HTTP Header authentication.

For an Okta catalog-based test integration:

1. In the Admin Console, go to Applications and Resources > Applications.
2. Select Browse App Catalog.

3. Search for SCIM 2.0 Test App (OAuth Bearer Token).

4. Select that catalog application and click Add Integration.
5. Complete the app's general or sign-on options. These settings do not configure Firstup SSO.

1. Under Sign-On Options, select Secure Web Authentication.
2. Select User sets username and password.

3. For Login URL, enter the organization’s Firstup Employee Experience URL.
4. Set Application username format to Okta username.
5. Set Update application username on to Create and update.
6. Complete the application setup.

1. Open the application's Provisioning tab.
2. Under Integration, select Configure API Integration or Edit.

3. Enable the API integration.
4. Enter the Firstup SCIM base URL for the test program's region.

1. Enter your access token.
2. Disable Import Groups.
3. Select Test the API credentials.
4. Save the integration only after the credential test succeeds.

Do not paste a standard client-credentials access token into a long-lived Okta connection. Access tokens issued by the authentication server expire after two hours, which will break provisioning. When the Firstup bearer token is rotated or revoked, update the Okta integration and retest the credentials.

Onced saved, under Provisioning > To App, enable the actions required for the implementation:

1. Select Edit and enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
2. Select Save.
3. Scroll down to map the user attributes.

Do not enable Group Push unless Firstup has confirmed that Groups SCIM is available for the program.

Scroll down in Provisioning > To App, confirm these mappings before provisioning a user:

SCIM attribute names are case-sensitive. Use the exact casing shown above.

Email addresses are also enforced as unique, but they behave differently: a create request carrying an email that already belongs to a different Firstup user is rejected with 409. Okta prevents duplicate emails within Okta itself, so in practice this surfaces when Firstup holds a record that Okta does not know about — one created by CSV import, in Creator Studio, by JIT provisioning, or by a previous Okta app instance.

A user can have up to 80 attributes in total, across standard and custom attributes. Map any other supported standard attributes using the User SCIM Attributes reference.

Firstup custom user attributes store additional organization-specific information that is not represented by the supported core or enterprise SCIM attributes. Firstup can use these values for audiences and other targeting features.

Use a standard Firstup SCIM attribute when one exists. Use customAttributes only for additional fields.

Custom attribute data rules

• The Firstup extension URN is urn:SocialChorus:1.0:User. The 1.0 segment is required, and the urn: prefix is required.
• customAttributes is an array of objects.
• Every object requires a name and a value.
• Attribute names and values are case-sensitive.
• Values must be strings. Send numbers and Boolean-like values as strings, for example "25" or "false".
• Do not send customAttributes as a Boolean, a plain object, or an array of bare strings.

Firstup's direct SCIM representation is:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:SocialChorus:1.0:User"
  ],
  "userName": "NHS10002",
  "urn:SocialChorus:1.0:User": {
    "customAttributes": [
      {
        "name": "facility",
        "value": "Northstar Health HQ"
      },
      {
        "name": "license_type",
        "value": "License B"
      }
    ]
  }
}

To inspect the schema definition directly, call:

GET /scim/v2/Schemas/urn:SocialChorus:1.0:User

Add a custom attribute to the Okta app profile

Repeat these steps for each custom attribute:

1. In the Okta Admin Console, go to Directory > Profile Editor.
2. Select the profile for the Firstup SCIM application, not the base Okta user profile.
3. Select Add Attribute.

4. Configure the attribute as follows:

Replace facility in the External name with the exact Firstup custom-attribute name. For example:

customAttributes.^[name=='license_type'].value

The External name selects the matching item inside the customAttributes array, and the External namespace identifies the Firstup extension schema that the array belongs to.

Map the Okta source value

Once the custom attributes has been saved, select Mappings from the Profile Editor.

1. Select Okta User to Firstup...

2. Find your custom attribute, and select Apply mapping on user create and update.

3. Enter a user in the Preview section to check the mapping.
4. Select Save Mappings.

After making these changes, you may need to force a sync.

Custom attribute validation errors

Firstup returns SCIM-compliant error bodies. A 422 response has this shape:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 422,
  "detail": [
    {
      "instancePath": "/roles",
      "message": "Only one role may be provided"
    }
  ]
}

1. Assign a test user to the Firstup SCIM app in Okta.
2. Confirm the user was created in Firstup, either in Creator Studio or with GET /scim/v2/Users.
3. If the user was created but a custom attribute is missing, retrieve the record and check whether the value appears under urn:SocialChorus:1.0:User. A missing value with a success status indicates the attribute was sent under an unrecognized schema key.
4. If provisioning failed, review the Okta system log and inspect the Firstup API response body.

When provisioning a group through Okta SCIM, if group members are included in the initial group creation (POST) request, Okta immediately issues a GET to confirm creation. That GET returns a 404 for 20 minutes, which breaks the sync.

This issue occurs only with Okta, not with other SCIM providers.

1. Create the group with the memberships box unticked.
2. Activate the group and push members. This results in an error.
3. Remove the group.
4. Create the group again, without pushing users. The group must use the exact same name.
5. Untick the memberships box.
6. Push users.

Why this works

Okta sometimes delays marking a group as enabled when members are included in the initial POST, which causes the immediate GET to fail. Separating group creation from member assignment avoids the timing and state issue that produces the 404 errors.

• Get started with Okta app integrations
• Okta explains how app instances are added to an external org