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

# SCIM provisioning

> Create, update, and deactivate CostGraph members from Okta or Microsoft Entra ID, and map groups to roles

SCIM provisioning lets your identity provider manage your CostGraph members. When you assign someone to the CostGraph app, they become a member. When you remove or deactivate them, they lose access. Groups you push map to CostGraph roles.

SCIM provisioning is available on CostGraph Cloud. It isn't available on self-hosted deployments yet.

## Before you begin

* You must be an owner of the CostGraph organization.
* Set up [single sign-on](/costgraph/security/sso) for your organization first if you want groups to map to roles. The group to role mapping lives in your single sign-on settings.
* Make sure each person's username in your identity provider is their email address.

## Create a provisioning token

1. In CostGraph, go to **Settings > Organization > Single sign-on**.
2. In the **Provisioning (SCIM)** card, click **Create token**. CostGraph shows the SCIM base URL and the token.
3. Copy the token now. CostGraph shows it a single time.

The SCIM base URL is `https://api.costgraph.ai/scim/v2`.

The card also shows when your identity provider last synced. To replace the token, click **Rotate token**. The old token stops working immediately, so update your identity provider right away. To stop provisioning, click **Revoke token**.

## Connect Okta

<Steps>
  <Step title="Turn on SCIM">
    In the Okta Admin Console, open your CostGraph app integration. On the **General** tab, click **Edit** under **App Settings**, set **Provisioning** to **SCIM**, and save.
  </Step>

  <Step title="Configure the connector">
    On the **Provisioning** tab, select **Integration** and click **Edit**. Enter these values:

    * **SCIM connector base URL**: `https://api.costgraph.ai/scim/v2`
    * **Unique identifier field for users**: `userName`
    * **Supported provisioning actions**: **Push New Users**, **Push Profile Updates**, and **Push Groups**
    * **Authentication Mode**: **HTTP Header**, with the provisioning token as the **Bearer** token
  </Step>

  <Step title="Test and save">
    Click **Test Connector Configuration**, then click **Save** after the test passes.
  </Step>

  <Step title="Choose what Okta changes">
    Under **Provisioning > To App**, click **Edit** and enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.
  </Step>

  <Step title="Assign people and push groups">
    On the **Assignments** tab, assign the people and groups who need CostGraph. On the **Push Groups** tab, push the groups you map to roles.
  </Step>
</Steps>

## Connect Microsoft Entra ID

<Steps>
  <Step title="Open provisioning">
    In the Microsoft Entra admin center, go to **Enterprise applications**, open your CostGraph app, and select **Provisioning**. Set **Provisioning Mode** to **Automatic**.
  </Step>

  <Step title="Enter the credentials">
    Under **Admin Credentials**, set **Tenant URL** to `https://api.costgraph.ai/scim/v2` and **Secret Token** to the provisioning token. Click **Test Connection**.
  </Step>

  <Step title="Check the mappings">
    Under **Mappings**, open the user mapping. Map `userName` to `userPrincipalName` if your user principal names are email addresses. Otherwise map it to `mail`. Keep the `active` mapping.
  </Step>

  <Step title="Set the scope and start">
    Under **Settings**, set **Scope** to **Sync only assigned users and groups**. Assign people and groups to the app, then click **Start provisioning**.
  </Step>
</Steps>

Microsoft Entra ID syncs about every 40 minutes, so changes can take that long to reach CostGraph.

## Members

CostGraph uses the username as the member's email address. A username that isn't an email address is refused, as are addresses on domains reserved for CostGraph staff.

A new member gets the default role from your single sign-on settings, or **Member** if you haven't set one. New members don't get workspace access automatically, the same as members who join through single sign-on. An admin grants workspace access in CostGraph.

## Deactivation

When you deactivate or unassign someone in your identity provider, CostGraph immediately:

* Deactivates their membership in your organization.
* Disconnects the apps they signed in to with their CostGraph account.
* Disables their personal API keys.

People whose email is on one of your verified domains are also signed out of CostGraph everywhere. Anyone else loses access to your organization on their next request.

Reactivating someone restores their membership. Their API keys and app connections stay disabled; they create new ones.

## Groups and roles

CostGraph maps pushed groups to roles with the [group to role mapping](/costgraph/security/sso#roles-from-groups) in your single sign-on settings. When someone is in several mapped groups, the highest role wins: **Admin**, then **Billing admin**, then **Member**. Someone in no mapped group gets the default role.

Provisioning doesn't make anyone an owner or change an owner's role. It can deactivate an owner, but not the last active owner.

## Supported requests

CostGraph supports the `Users` and `Groups` resources. You can filter users by `userName` or `externalId` and groups by `displayName` or `externalId`, with the `eq` operator.

Requests are rate limited per organization. When you go over the limit, CostGraph answers `429` with a `Retry-After` header, and Okta and Microsoft Entra ID retry on their own.

The audit log records every provisioning action.

## Common errors

The following table lists common errors and how to fix them.

| Symptom | Cause | Fix |
| - | - | - |
| `401 Unauthorized` | The token was rotated or revoked | Create or rotate the token and update your identity provider |
| `409 Conflict` when creating a user | A member with that email already exists | Match users on `userName` so your identity provider links the existing member |
| A provisioned member can't see any costs | New members have no workspace access | Grant the member access to a workspace in CostGraph |


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