Prepare your SCIM service

On This Page

The first step in delivering your SCIM integration is preparing a SCIM-compliant API server to host your SCIM service.

Okta supports lifecycle provisioning using either Version 2.0 and Version 1.1 of the SCIM protocol.

If your service already supports the SCIM protocol, it is important that you review the Okta SCIM reference documentation to understand the specifics of how Okta implements the SCIM protocol:

If you haven't yet implemented SCIM, Okta recommends that you use Version 2.0 of the SCIM protocol.


Another important part of the planning process is determining which Okta provisioning features your SCIM API can or should support. At a minimum, Okta requires that your SCIM Version 2.0 API implements the following features.

API endpoints

The API endpoint for your SCIM API must be secured using the Transport Layer Security (opens new window) protocol. Connections through this secure layer are routed by using the https:// prefix for your URL.

You must support the URL structure described in the "SCIM Endpoints and HTTP Methods" section of RFC7644 (opens new window).


Your SCIM API must be secured against anonymous access.

Okta supports authentication against SCIM APIs using any one of the following methods:

If you are using OAuth 2.0, then after successfully authorizing Okta to use your SCIM API, your application's authorization server redirects the user back to Okta, with either an authorization code or an access token.

If you are going to publish your integration to the OIN catalog, Okta requires that all SCIM applications support all of the following redirect URIs (opens new window):


where the {appName} is a unique identifier provided to you after your integration is submitted and processed by Okta. If, for any reason, your unique {appName} identifier isn't provided to you after the initial review, send an email to

Base URL

You can choose any Base URL for your API endpoint. Note that a Base URL can't contain the underscore _ character.

If you are implementing a new SCIM API, we suggest using /scim/v2/ as your Base URL. For example:

If you have multiple Okta orgs using your service, you can use the same SCIM server for all of them. To do so, one way is to implement a 1:1 client to tenant subdomain for each org running on the SCIM server. For example, if you have three Okta orgs:


You can pass a Base URL containing the name of the org:


On your SCIM server, you can read which subdomain the request is coming from and route the request to the appropriate tenant for the Okta org.

Basic user schema

Okta requires that your SCIM implementation be able to store the following four user attributes:

  • User ID: userName
  • First Name: name.givenName
  • Last Name: name.familyName
  • Email: emails

Note: Keep your User ID value distinct from the user's email address. Many systems use an email address as a user identifier, but this isn't recommended, as email addresses often change. Using a distinct User ID to identify user resources prevents future issues.

Note that Okta supports more than those four user attributes. However, these are the base attributes that you must support. The full schema of user attributes supported by SCIM 2.0 is described in section 4 of RFC 7643 (opens new window).

If your integration supports user attributes beyond those four base attributes, you can add support for additional attributes to your SCIM API. In some cases, you might need to configure Okta to map non-standard user attributes into the user profile for your application. See the Check the attributes and corresponding mappings step in this guide, or the "Add custom attributes to an Okta user profile" section in the Work with Okta user profiles and attributes (opens new window) topic in the Okta product documentation.

Unique ID

In addition to the basic user schema attributes, your SCIM API must also specify a unique identifier for each user resource.

Section 3.1 (opens new window) of the SCIM specification asserts that the id attribute is used to uniquely identify resources. This unique identifier:

  • Is assigned a value by the service provider (your application) for each SCIM resource
  • Is always issued by the service provider (your application) and not specified by the client (Okta)
  • Must be included in every representation of the resource
  • Cannot be empty
  • Must be unique across the SCIM service provider's entire set of resources
  • Cannot be reassigned
  • Must be a stable identifier, meaning that it doesn't change when the same resource is returned in subsequent API requests
  • Must be case-sensitive and read-only
  • Cannot be hidden from the API request

A best practice is to use a generated globally unique identifier (GUID) for this value.

Note: The string bulkId is a reserved keyword and must not be used within any unique identifier value.

Active resources

Okta user management requires that your SCIM API supports an active attribute for each user resource that can be set to true or false to denote a resource as "active" or "inactive".

Example implementations

There are numerous examples of how to implement SCIM servers and applications. Here are a few to get you started:

A full list of implementations, both open-source and proprietary, is available at (opens new window).

SCIM facade

Sometimes it isn't feasible for your cloud-based application to natively support a SCIM API. An alternative option is to build and host your own SCIM facade middleware that translates between the Okta SCIM API connection and the cloud application's proprietary API. The Okta integration connection is then made to this SCIM facade.

Provision to on-premises applications

This provisioning guide targets cloud-based applications, but Okta does have a solution for on-premise applications. See Configuring On Premises Provisioning (opens new window) for details about the Okta agent-based provisioning solution.