Skip to content

Integrations

SCIM provisioning setup guide

Let your identity provider manage who has Mestra access. When someone joins, they’re added. When their role changes, Mestra follows. When they leave, their access ends. This guide covers Okta and Microsoft Entra; any identity provider that supports SCIM 2.0 works the same way. SCIM is part of Enterprise, for contract and Network customers. It isn’t part of Studio or the free trial. Talk to us to add it.

Prerequisites

  • A Mestra organisation on Enterprise (a contract, or Network).
  • An owner of that Mestra organisation.
  • Your company’s email domain verified in Mestra. Mestra only provisions people at domains your organisation has verified. See step 1 of the Okta setup guide; verifying is the same for any identity provider.
  • An admin in your identity provider who can set up app provisioning.

Supported features

  • Create users. People you assign to Mestra are added to your organisation.
  • Update user attributes. Name and Mestra role.
  • Deactivate users. Unassigning someone, or deactivating them, removes them from your organisation. Their sessions, API keys and app connections end at once.
  • Import users. Your identity provider can match people who are already members, by email.
  • Roles as entitlements. Each person has one Mestra role: Owner, Editor or Reviewer.

Not supported: groups (assign people, or use your identity provider’s groups to assign them), password sync (Mestra has no passwords), and changing someone’s email address (contact support).

What your people see

  • New members sign in as usual: an email link, Google or Microsoft, or Okta if your organisation has SSO.
  • Roles. Someone added without a role is a Reviewer, the role with the least access. Mestra always keeps at least one owner, so a change that would leave your organisation without one is refused.
  • Team. In Mestra, people your identity provider manages show Managed by your identity provider. Change their role in your identity provider. An owner can still remove them in Mestra.
  • Emails. Your owners get an email when your identity provider makes someone an owner or takes the role away.
  • Leavers. When someone leaves, the service API keys, workload sign-ins, webhook endpoints and invites they set up are turned off, and your owners get one email listing them.

1. Make a provisioning token in Mestra

  1. An owner opens Settings > Sign-in and finds Provisioning (SCIM).
  2. Copy the Base URL: https://app.withmestra.com/scim/v2.
  3. Press Make token and copy it. You won’t see it again.

Rotate token replaces it at once; update your identity provider straight after. Remove token stops provisioning and leaves your people as they are.

2a. Okta

Mestra’s listing in the Okta catalogue includes provisioning. Until it’s there, add provisioning to the Mestra app you made for sign-in: on its General tab, under App Settings, set Provisioning to SCIM.

  1. In the Okta Admin Console, open the Mestra app, then Provisioning > Integration > Edit.
  2. Enter:
    • SCIM connector base URL: https://app.withmestra.com/scim/v2
    • Unique identifier field for users: userName
    • Supported provisioning actions: Push New Users, Push Profile Updates, and Import New Users and Profile Updates. Leave Push Groups off.
    • Authentication Mode: HTTP Header. Paste the token as the Authorization value.
  3. Press Test Connector Configuration, then Save.
  4. Under Provisioning > To App > Edit, turn on Create Users, Update User Attributes and Deactivate Users. Save.
  5. Roles. With Okta Identity Governance, Mestra’s roles appear as entitlements on the app’s Governance tab: assign Owner, Editor or Reviewer there. Without it, people are added as Reviewers and an owner sets roles in Mestra.
  6. Assign people (or groups of people) to the Mestra app on its Assignments tab.

2b. Microsoft Entra

  1. In the Microsoft Entra admin center, go to Enterprise applications > New application > Create your own application. Name it Mestra and choose Integrate any other application you don’t find in the gallery.

  2. Add the three Mestra roles first. Open App registrations > Mestra > App roles and create:

    Display name Value Allowed member types
    Owner owner Users/Groups
    Editor editor Users/Groups
    Reviewer viewer Users/Groups
  3. Back in Enterprise applications > Mestra > Provisioning, set Provisioning Mode to Automatic and enter:

    • Tenant URL: https://app.withmestra.com/scim/v2
    • Secret Token: the token from Mestra

    Press Test Connection, then Save.

  4. Under Mappings > Provision Microsoft Entra ID Users, add a mapping:

    • Mapping type: Expression
    • Expression: SingleAppRoleAssignment([appRoleAssignments])
    • Target attribute: roles[primary eq "True"].value

    Make sure userName is mapped to your people’s email address (usually userPrincipalName or mail).

  5. Under Users and groups, assign people with one of the three roles. Entra’s default User role isn’t a Mestra role, so always pick Owner, Editor or Reviewer.

  6. Set Provisioning Status to On and save.

Provisioning from Entra doesn’t change how people sign in: they can still use Microsoft, an email link, or Okta if your organisation has SSO.

Troubleshoot

What you see Why What to do
The connection test fails with 401 The token is wrong, was rotated or removed. Make a new token in Mestra and paste it again.
The connection test fails with 403 Your Mestra subscription doesn’t include provisioning. Check your subscription in Mestra under Billing, or talk to us.
“Use an email at a domain your organisation verified in Mestra.” The person’s email isn’t at a domain your organisation has verified. Verify the domain in Settings > Sign-in, then retry.
“This is the organisation’s only owner.” The change would leave your organisation with no owner. Make someone else an owner first.
A role value is refused (Entra) The person has Entra’s default role, or a role that isn’t Owner, Editor or Reviewer. Assign one of the three Mestra roles.
Someone’s email changed in your identity provider and syncing stopped Mestra doesn’t change email addresses through provisioning. Email support@withmestra.com.

Still stuck? Email support@withmestra.com.