Skip to main content
Table of Contents

Setup Guide - Okta SCIM

Configuring SCIM Provisioning in Okta for LinearB. Use this guide to configure SCIM-based user provisioning between Okta and LinearB. SCIM lets Okta automatically create, update, and deactivate users…

Table of Contents

Configuring SCIM Provisioning in Okta for LinearB

Use this guide to configure SCIM-based user provisioning between Okta and LinearB. SCIM lets Okta automatically create, update, and deactivate users in LinearB based on your identity provider, including role and team-scope information.

Overview

  • SCIM version: V2.0
  • Supported schema: urn:ietf:params:scim:schemas:core:2.0:User
  • Provisioning direction: Okta → LinearB

What SCIM does

  • Automatically provisions new users into LinearB when they’re assigned to the LinearB app in Okta.
  • Updates user attributes (including role and team scope) when they change in Okta.
  • Deactivates LinearB users when they are deactivated in Okta.
  • Reduces manual administration and keeps identity and access in sync.

Before you begin

  • Plan: SCIM provisioning is available to Enterprise customers.
  • Permissions: Okta admin and LinearB admin access.
  • LinearB access: Ability to open Company Settings in LinearB.
  • SCIM API token: Generated from LinearB (created in this guide).

Step 1 – Enable SCIM in LinearB

1.1 Create an API token

  1. In LinearB, go to Company Settings → API Tokens.
  2. Click Create API Token, enter a descriptive label (for example, Okta SCIM), and click Create.
  3. Copy the new token immediately and store it securely. You will not be able to view it again later.

1.2 Enable SCIM provisioning

  1. In Company Settings → SCIM.
  2. If you do not see the SCIM tab, reach out to your LinearB contact or LinearB Support to enable SCIM for your account.
  3. Enable SCIM and click Save.

You now have:

  • An active SCIM API token.
  • SCIM provisioning enabled in LinearB.

Step 2 – Configure SCIM in Okta

2.1 Enable SCIM provisioning in Okta for the LinearB app

  1. In the Okta Admin Console, open your LinearB application.
  2. From the app, go to General Settings (or the Provisioning tab, depending on your Okta UI).
  3. Enable SCIM provisioning / API integration for the app.

2.2 Set up the SCIM connection

  1. Open the Provisioning tab in the LinearB Okta app.
  2. Click Edit in the SCIM connection section and configure:
  • SCIM Connector Base URL: https://public-api.linearb.io/scim/api/v2
  • Unique Identifier Field for Users: email
  • Supported Provisioning Actions:
    • Push New Users
    • Push Profile Updates
    • Push Groups
  • Authentication Mode: HTTP Header
  • HTTP Header / API Token: paste the LinearB API token you created in Step 1.
  1. Save your changes.
  2. Run Test Connector Configuration to validate the connection.

If the connector test fails, double-check the SCIM base URL and that the API token is correct and active.

2.3 Enable provisioning actions

  1. Still in the LinearB Okta app, under Provisioning to App, enable:
  • Create Users
  • Update User Attributes
  • Deactivate Users
  1. Click Save to confirm the settings.

When these actions are enabled, Okta will create, update, and deactivate LinearB users automatically based on assignments to the LinearB application.

Step 3 – Configure user attributes and access provisioning

LinearB supports standard SCIM core attributes and two optional custom attributes for controlling roles and team access:

  • userRole – Sets the user’s LinearB role. If omitted, the user is provisioned as a Viewer.
  • scopeTeamIds – Identifies the LinearB teams the user can access. If omitted, the user is created without team scope.
Important: Both attributes are optional. However, explicitly providing userRole and scopeTeamIds is recommended when users require access to the main LinearB application.

3.1 Create custom attributes on the LinearB app profile

  1. In Okta Admin, go to Directory → Profile Editor.
  2. Select the LinearB application profile.
  3. Click Add Attribute and create the custom attributes you intend to use.
User Role attribute (userRole)
  • Display name: User role
  • Variable name: userRole
  • External name: userRole
  • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
  • Data type: String
  • Description: LinearB user role
  • Enum values:
    • ADMIN → admin
    • EDITOR → editor
    • VIEWER → viewer
  • Attribute required: No
  • Attribute type: Personal or Group, depending on your provisioning model.

If userRole is not provided, LinearB assigns the user the Viewer role.

Team Scope attribute (scopeTeamIds)
  • Display name: Team scope
  • Variable name: scopeTeamIds
  • External name: scopeTeamIds
  • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
  • Data type: Number array
  • Description: LinearB teams accessible to the user
  • Attribute required: No
  • Attribute type: Personal or Group, matching your provisioning model.
A user provisioned without scopeTeamIds is created without team scope. The user cannot access the main LinearB application, but can access Surveys.

Save each attribute after configuration.

3.2 Add corresponding fields to the Okta User profile

To send role and team-scope values from an Okta user to LinearB, add matching fields to the Okta User profile.

  1. In Directory → Profile Editor, select Okta User.
  2. Add custom attributes corresponding to userRole and scopeTeamIds.
  3. Map the Okta User fields to the LinearB app attributes created in Step 3.1.

Once mapped, Okta sends the configured LinearB role and team scope when the user is provisioned or updated.

Step 4 – Assign users and groups

4.1 Assign users or groups to the LinearB app

  1. In Okta, open the LinearB application.
  2. Go to the Assignments tab.
  3. Click Assign → Assign to People or Assign to Groups.
  4. Select the users or groups you want to provision and click Assign.

4.2 Set the user role and team scope

The following values are optional, but configuring them is recommended for users who require access to LinearB:

  • Set User Role to one of:
    • admin
    • editor
    • viewer
    If no value is supplied, the user is assigned the Viewer role.
  • Set Team Scope (scopeTeamIds) to the LinearB team IDs the user should access.
Leave scopeTeamIds empty only when the user should be provisioned without access to the main LinearB application, such as a user who requires access to Surveys only.

To find LinearB team IDs, use the LinearB public Teams API .

4.3 Validate provisioning in LinearB

  1. In LinearB, go to Company Settings → Users & Teams.
  2. Confirm that newly assigned Okta users appear in the list.
  3. Verify that each user has the expected role and team assignments.
  4. For a user intentionally provisioned without team scope, verify that their access matches the intended Survey-only use case.

Troubleshooting

Provisioning fails or the connector test fails
  • Verify that the SCIM Connector Base URL is exactly https://public-api.linearb.io/scim/api/v2.
  • Confirm that the API token is valid, active, and pasted correctly in the HTTP header.
  • Ensure HTTP Header is selected as the authentication mode.
  • Check the Okta system logs for detailed error messages.
Users are not being created
  • Confirm that the users or groups are assigned to the LinearB app in Okta.
  • Make sure Create Users is enabled under Provisioning to App.
  • Review the Okta system log for profile-mapping or provisioning errors.
User role is not updating
  • Ensure Update User Attributes is enabled in the provisioning settings.
  • Verify that userRole is mapped correctly from the Okta User profile to the LinearB app profile.
  • Confirm that the supplied value is admin, editor, or viewer.
  • If userRole is omitted, LinearB assigns the user the Viewer role.
User cannot access the main LinearB application
  • Check whether scopeTeamIds was included when the user was provisioned.
  • A user provisioned without scopeTeamIds has no team scope and cannot access the main LinearB application.
  • Users without team scope can still access Surveys.
  • If the user requires application access, assign the appropriate LinearB team IDs in Okta and push the profile update again.
User is not assigned to the expected teams
  • Confirm that scopeTeamIds contains the correct LinearB team IDs.
  • Verify that the supplied IDs correspond to existing LinearB teams.
  • Confirm that scopeTeamIds is mapped correctly from the Okta User profile to the LinearB app profile.
  • Check for conflicting manual team assignments in LinearB.
Changes made in Okta are not appearing in LinearB
  • Ensure Update User Attributes is enabled under Provisioning to App.
  • Confirm that the relevant custom attribute is mapped correctly.
  • Review the Okta system log for failed update requests.
  • If necessary, use Okta to retry the provisioning task or push the user’s profile again.
User already exists with a different username
  • If a user was created manually in LinearB before SCIM provisioning, their username may not match the Okta value.
  • Review the existing LinearB user before removing or reassigning the user through Okta.
  • Contact LinearB Support if you need help reconciling the existing account without losing its associated data.

FAQs

Is userRole required?
No. If userRole is omitted, LinearB provisions the user with the Viewer role. Explicitly setting the role is recommended.

Is scopeTeamIds required?
No. If scopeTeamIds is omitted, LinearB creates the user without team scope.

What can a user access without team scope?
A user without team scope cannot access the main LinearB application, but can access Surveys.

Can SCIM automatically assign users to teams?
Yes. Provide the relevant LinearB team IDs through scopeTeamIds.

Which identity provider is supported for SCIM?
SCIM provisioning is currently supported with Okta.

Need help?
If you encounter issues or have edge cases not covered here, please contact LinearB Support.

How did we do?

Setup Guide - Okta SAML SSO

Using Multiple Domains with SSO

Contact