---
title: SCIM
intro: 'You can automate user creation and team memberships using the SCIM API.'
versions:
  ghes: '>=3.6'
topics:
  - API
miniTocMaxHeadingLevel: 3
---

{% note %}

**Note:** The SCIM API for {% data variables.product.product_name %} is currently in private beta and subject to change. To access the private beta and test the API, contact your account manager on {% data variables.contact.contact_enterprise_sales %}.

{% endnote %}

## About the SCIM API

{% data variables.product.product_name %} provides a SCIM API for use by SCIM-enabled Identity Providers (IdPs). An integration on the IdP can use the API to automatically provision, manage, or deprovision user accounts on a {% data variables.product.product_name %} instance that uses SAML single sign-on (SSO) for authentication. For more information about SAML SSO, see "[About SAML for enterprise IAM](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam)."

The SCIM API is based on SCIM 2.0. For more information, see the [specification](https://www.simplecloud.info/#Specification).

### SCIM endpoint URLs

An IdP can use the following root URL to communicate with the SCIM API for a {% data variables.product.product_name %} instance.

```
{% data variables.product.api_url_code %}/scim/v2/
```

Endpoint URLs for the SCIM API are case-sensitive. For example, the first letter in the `Users` endpoint must be capitalized.

```shell
GET /scim/v2/Users/{scim_user_id}
```

### Authenticating calls to the SCIM API

The SCIM integration on the IdP performs actions on behalf of an enterprise owner for the {% data variables.product.product_name %} instance. For more information, see "[Roles in an enterprise](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners)."

To authenticate requests to the API, the person who configures SCIM on the IdP must use a personal access token (classic) with `admin:enterprise` scope, which the IdP must provide in the request's `Authorization` header. For more information about personal access tokens (classic), see "[Creating a personal access token](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)".

{% note %}

**Note:** Enterprise owners must generate and use a personal access token (classic) for authentication of requests to the SCIM API. {% ifversion ghes > 3.8 %}Fine-grained personal access tokens and {% endif %}GitHub app callers are not supported at this time.

{% endnote %}

### About mapping of SAML and SCIM data
  
The {% data variables.product.product_name %} instance links each user who authenticates successfully with SAML SSO to a SCIM identity. To link the identities successfully, the SAML IdP and the SCIM integration must use matching SAML `NameID` and SCIM `userName` values for each user.

{% ifversion ghes > 3.7 %}
{% note %}

**Note:** If the {% data variables.product.product_name %} uses Azure AD as a SAML IdP, {% data variables.product.product_name %} will also check the SCIM `externalId` claim and SAML `http://schemas.microsoft.com/identity/claims/objectidentifier` claim to match users first, instead of using `NameID` and `userName`. 

{% endnote %}
{% endif %}

### Supported SCIM user attributes

The SCIM API's `User` endpoints support the following attributes within a request's parameters.

| Name | Type | Description |
| :- | :- | :- |
| `displayName` | String | Human-readable name for a user. |
| `name.formatted` | String | The user's full name, including all middle names, titles, and suffixes, formatted for display.
| `name.givenName` | String | The first name of the user. |
| `name.familyName` | String | The last name of the user. |
| `userName` | String | The username for the user, generated by the IdP. Undergoes [normalization](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization) before being used. 
| `emails` | Array | List of the user's emails. |
| `roles` | Array | List of the user's roles. |
| `externalId` | String | This identifier is generated by an IdP provider. You can find the `externalId` for a user either on the IdP, or by using the [List SCIM provisioned identities](#list-scim-provisioned-identities-for-an-enterprise) endpoint and filtering on other known attributes, such as a user's username or email address on the {% data variables.product.product_name %} instance. |
| `id` | String | Identifier generated by the instance's SCIM endpoint. |
| `active` | Boolean | Indicates whether the identity is active (`true`) or should be suspended (`false`). |