> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Provisioning (SCIM, Okta)

> Add, remove, and set roles for your Mesh API members from Okta, using SCIM 2.0.

With user provisioning, Okta manages who is in your Mesh organization. Assign someone in Okta and they join; unassign them and they leave, with their API keys suspended. Okta groups can make people admins. Mesh speaks SCIM 2.0, the standard Okta uses to push these changes.

Provisioning works alongside [single sign-on](https://developers.meshapi.ai/docs/getting-started/single-sign-on.md): SSO decides how people sign in, provisioning decides who is a member. Set up SSO first.

> [!NOTE]
>
> User provisioning is available to **Enterprise** customers, the same as SSO. Email [contact@meshapi.ai](mailto:contact@meshapi.ai) to turn it on for your organization.

## Before you start

You need:

* **SSO set up, with your email domain verified.** Provisioning only creates people on that domain or its subdomains. See [Single Sign-On](https://developers.meshapi.ai/docs/getting-started/single-sign-on.md).
* **An owner or admin role** in the Mesh organization. Custom roles and admin keys cannot set up provisioning.
* **Admin access to your Okta org.**

## Set up provisioning

Okta cannot provision through the OIDC app you created for SSO, so provisioning uses a second app from Okta's catalog. People keep signing in through the first one. Mesh matches the two by email.

**1. Create a provisioning token in Mesh**

1. In the Dashboard, go to **Settings → Single sign-on**. Below your identity provider, find **User provisioning (SCIM)** and click **Set up provisioning**.
2. Copy both values from the yellow box:
   * **SCIM base URL**: `https://auth.meshapi.ai/api/auth/scim/v2`
   * **Token**

The token is shown once. Mesh keeps only a digest of it. If you lose it, click **New token**.

**2. Add the SCIM app in Okta**

1. In the Okta Admin Console, go to **Applications → Applications → Browse App Catalog**.
2. Search for **SCIM 2.0 Test App (Header Auth)** and click **Add Integration**.
3. Name it `Mesh SCIM`. Under **Application visibility**, tick **Do not display application icon to users**: people sign in through your SSO app, not this one.
4. Click **Done**.

**3. Connect it to Mesh**

1. Open the **Mesh SCIM** app → **Provisioning** → **Configure API Integration**, and tick **Enable API integration**.

2. Fill in:

   | Field | Value |
   | - | - |
   | Base URL | `https://auth.meshapi.ai/api/auth/scim/v2` |
   | API Token | `Bearer ` followed by the token from step 1 |

3. Click **Test API Credentials**, then **Save**.

> [!WARNING]
>
> Type `Bearer` and a space before the token. This app sends the field as the whole `Authorization` header, so a bare token fails with **SCIM bearer token is required**.

**4. Turn on the provisioning actions**

1. Still on **Provisioning**, choose **To App** and click **Edit**.
2. Tick **Create Users**, **Update User Attributes**, and **Deactivate Users**. Leave **Sync Password** off; Mesh has no passwords.
3. Click **Save**.

Do this before assigning anyone. People assigned while these are off fail to sync until you retry them.

**5. Assign people**

On the **Mesh SCIM** app's **Assignments** tab, assign the same people or groups as your SSO app. Each one appears under **Settings → People** in Mesh within seconds.

Assigning a group to both apps keeps sign-in and membership in step.

## Map Okta groups to roles

By default everyone Okta provisions is a **Member**. To make the people in an Okta group **Admins**:

**1. Push the group from Okta**

On the **Mesh SCIM** app, open **Push Groups → Push Groups → Find groups by name**, pick the group, and click **Save**.

**2. Map it in Mesh**

1. Under **Settings → Single sign-on → User provisioning (SCIM) → Group roles**, click **Add group**.
2. Pick the group by name and choose **Admin**.
3. Click **Save**.

Saving applies the map to existing members straight away. If the confirmation says the roles **apply at the next sync**, they update the next time Okta pushes a change.

How roles resolve:

* **Someone in no mapped group is a Member.** Taking them out of the group demotes them.
* **The highest role wins** when someone is in several mapped groups.
* **Renaming the group in Okta changes nothing.** The map follows the group, not its name.
* **Provisioning only moves people between Admin and Member.** It never changes an owner's or a viewer's role; set those in Mesh. A viewer Okta unassigns still leaves.
* **A manual role change can be overwritten.** If you make someone an Admin in Mesh but no mapped group says so, the next sync makes them a Member again. Use a group instead.

If Okta has pushed more than 200 groups, the picker shows the first 200; type to search the rest.

## What each change does

| In Okta | In Mesh |
| - | - |
| Assign someone | They join as a Member. If they already have a Mesh account with that email, Mesh links it rather than creating a second one |
| Unassign or deactivate someone | They leave the organization. Their API keys are suspended, unless you turned off **Suspend their API keys** under **Settings → People** |
| Assign them again | They rejoin as a Member. Their suspended keys stay suspended; an admin can reactivate them |
| Add them to a mapped group | Their role changes to the group's role |

Some changes are deliberately one-way:

* **The organization owner is never removed or re-roled**, whatever Okta sends.
* **Removing someone in Mesh sticks.** If you remove a member under **Settings → People**, provisioning does not re-add them, even while Okta still assigns them.
* **Access ends within 15 minutes.** Suspended API keys stop at once. A Dashboard session they already hold keeps working until its current token expires, at most 15 minutes, and they cannot get a new one.

Okta can only create people on your verified SSO domain or its subdomains. Anyone else is refused, and Okta shows the push as failed.

## Manage the connection

Everything below is on **Settings → Single sign-on → User provisioning (SCIM)**, and needs a signed-in owner or admin. Anyone who can read your org's settings can see the card.

### See what is set up

The card shows the **SCIM base URL**, each token with its expiry and when Okta last used it, and the **Group roles** map. Tokens themselves are never shown again after you copy them.

### Replace a token

**1. Create the new token**

Click **New token** and copy it from the yellow box. The old token keeps working.

**2. Put it in Okta**

In the **Mesh SCIM** app → **Provisioning → Integration → Edit**, replace the **API Token** with `Bearer ` followed by the new token. Click **Test API Credentials**, then **Save**.

**3. Revoke the old token**

Back on the card, click **Revoke** next to the old token.

Tokens expire after a year. Replace one before then, or Okta's pushes start failing.

### Revoke a token

Click **Revoke** next to it. It stops working at once, and Okta's next push fails until it has a working token.

### Change the group map

Under **Group roles**, change a group's role or click the delete icon next to it, then **Save**. The change applies to existing members straight away.

### Turn off provisioning

Click **Turn off provisioning** and confirm. Okta can no longer add or remove anyone, and the people it added stay members. To turn it back on, click **Set up provisioning** again and give Okta the new token.

> [accordion] Read the setup with an admin key
>
> An [admin key](https://developers.meshapi.ai/docs/getting-started/admin-keys.md) holding `org:read` can read the same setup the card shows, for audits or monitoring. It cannot change anything.
>
> ```bash theme={null}
> curl https://api.meshapi.ai/v1/orgs/current/scim \
>   -H "Authorization: Bearer $MESH_ADMIN_KEY"
> ```
>
> ```bash theme={null}
> curl "https://api.meshapi.ai/v1/orgs/current/scim/groups?search=admins" \
>   -H "Authorization: Bearer $MESH_ADMIN_KEY"
> ```

## Troubleshooting

Okta's **Reports → System Log** and the **Mesh SCIM** app's push status show why a change did not arrive.

| What you see | Cause | Fix |
| - | - | - |
| **SCIM bearer token is required** when testing credentials | The API Token field has no `Bearer ` prefix | Enter `Bearer <token>` |
| **Unauthorized** with the prefix present | The token was revoked, expired, or mistyped | Click **New token** in Mesh and paste it in Okta |
| Assigned people show a sync error and never appear in Mesh | **Create Users** was off when they were assigned | Turn it on (step 4), then retry them from Okta's **Dashboard → Tasks** |
| A push fails for one person | Their email is not on your verified SSO domain | Fix their primary email in Okta, or verify that domain in Mesh |
| Someone removed in Mesh does not come back when re-assigned | Removal in Mesh sticks | Re-invite them under **Settings → People** |
| The group picker says **Push a group from your IdP to map it here** | Okta has not pushed any group | Push one (see [Map Okta groups to roles](#map-okta-groups-to-roles)) |
| **User provisioning** is missing from the SSO page | Your organization does not have the Enterprise entitlement | Contact us |

## Related

> [card] [Single Sign-On (Okta)](https://developers.meshapi.ai/docs/getting-started/single-sign-on.md)
>
> Set up sign-in with Okta first.

> [card] [Organizations & Teams](https://developers.meshapi.ai/docs/getting-started/organizations.md)
>
> Roles, and what happens to keys when someone leaves.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.