SCIM API

The User Management API in Amplitude provides a programmatic solution to provisioning and group management through a public API. This enables administrators to quickly and easily manage their organizations at scale and integrate the provisioning process with other tools, including Identity Providers.

This guide provides detailed documentation on the specific routes supported by Amplitude's implementation of the SCIM 2.0 Standard, with specific attention to any details useful for debugging issues with a SCIM integration.

For a guide detailing how to integrate the SCIM API with an Identity Provider (e.g. Okta, JumpCloud) or how to enable the SCIM API for an organization, please see our Help Center Guide.

API Usage Limits

The SCIM API supports 100 requests per minute per organization. This restriction can be lifted for burst requests on a per-request basis. Please contact our support team or a customer success manager for more information.

Authorization

The SCIM API is authorized via Bearer Token in the Authorization Header. The token should equal the key that is generated on the Access and SSO page in the Settings Tab of Amplitude (see the Help Center Guide for a more detailed guide on how to find and save this key).

curl https://core.amplitude.com/scim/1/Users \
-H 'Accept: application/json' \
-H "Authorization: Bearer MY_PRIVATE_SCIM_KEY"

Base URL

The Base URL for the SCIM API is https://core.amplitude.com/scim/1/, and all routes can be formed according to the SCIM Standard. This URL does not change between organizations, as the SCIM key used in authentication is used to determine which organization the requests are directed toward.

Important: Although the route is suffixed with a 1, this does not mean that Amplitude implements the SCIM 1.1 Standard. This is to denote our version of this implementation, future-proofing for new iterations of the API that introduce breaking changes without disrupting service for current consumers.

User Routes

This section details routes and information that deal with user management.

Important: Users are defined as active within Amplitude whether or not they have accepted the invitation and have logged in once to the organization within Amplitude. This prevents Identity Providers from resending invitations unnecessarily to invited/pending users.

Important Users who are created/newly provisioned through the POST route of the Users SCIM API will be sent an invitation through email to complete sign-up.

Supported User Fields

Amplitude currently supports the following fields in the core User Schema:

GET /Users

Gets a list of users within Amplitude for that organization. This includes both pending and joined users, and supports pagination and filtering.

curl https://core.amplitude.com/scim/1/Users?filter=userName%20eq%20%datamonster%40amplitude.com%22&startIndex=1&count=100 \
-H 'Accept: application/json' \
-H "Authorization: Bearer MY_PRIVATE_SCIM_KEY"

{
  schemas: ['urn:ietf:params:scim:api:messages:2.0:ListResponse'],
  startIndex: 1,
  itemsPerPage: 100,
  totalResults: 1,
  Resources: [
    {
      schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
      id: '[email protected]',
      userName: '[email protected]',
      name: {
        givenName: 'data',
        familyName: 'monster',
      },
      active: true,
      emails: [{
        value: '[email protected]',
        primary: true,
      }],
      meta: {
        resourceType: 'User',
      }
    }
  ]
}

GET /Users/:id

Gets a single user within Amplitude for that organization. The id must be a valid email, though not case sensitive.

curl https://core.amplitude.com/scim/1/Users/[email protected] \
-H 'Accept: application/json' \
-H "Authorization: Bearer MY_PRIVATE_SCIM_KEY"

{
  schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
  id: '[email protected]',
  userName: '[email protected]',
  name: {
    givenName: 'data',
    familyName: 'monster',
  },
  active: true,
  emails: [{
    value: '[email protected]',
    primary: true,
  }],
  meta: {
    resourceType: 'User',
  }
 }
}

POST /Users

Creates a new user within Amplitude, sends an invitation link to the email requested, and returns a 201 Resource Created response if successful. The ID and Username must be valid emails, and the user must not have been previously invited/provisioned to your Amplitude organization to succeed.

The request body for the POST route should be a valid SCIM User Resource. Note the Groups field on the user will be ignored. If a user should be added to a group, please call the API routes pertaining to the group and not the user.

curl https://core.amplitude.com/scim/1/Users/[email protected] \
--request POST \
-H "Content-Type: application/scim+json" \
-H "Authorization: Bearer MY_PRIVATE_SCIM_KEY" \
--data 'YOUR_SCIM_BODY'

{
  schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
  id: '[email protected]',
  userName: '[email protected]',
  name: {
    givenName: 'data',
    familyName: 'monster',
  },
  emails: [{
    value: '[email protected]',
    primary: true,
  }],
  meta: {
    resourceType: 'User',
  }
 }

If successful, the response should contain the resource that is the same as the resource.

PUT /Users/:id

Updates an existing user with the given ID within Amplitude. The ID must be a valid email, and the user must have been previously invited to Amplitude.

If the active schema field is set to false on the request body, the user will be removed from the organization and all access is lost. If this action is taken on a Pending User (i.e. invite has been sent but has not yet accepted the invite), the invitation is revoked.

PATCH /Users/:id

Updates an existing user with the given ID within Amplitude, as according to the SCIM PATCH specification. The ID must be a valid email, and the user must have been previously invited to Amplitude.

This follows the similar caveats as the PUT route - the email cannot be changed and the user will lose access to the organization if the active field is patched to false.

DELETE /Users/:id

Deletes an existing user with the given ID within Amplitude, and returns a 204 No Content response if successful. The ID must be a valid email, and the user must have been previously invited to Amplitude.

If this action is taken on a Pending User (i.e. invite has been sent but has not yet accepted the invite), the invitation is revoked.

Group Routes

This section details the requests and responses available for Permission Group related API's. We support all core fields of the Group Schema, with users within groups returned with the fields listed in the User Fields section detailed above.

For this iteration of the SCIM API, all group ID's are numeric.

Important: If a user is added to a group without previously having been invited to this organization in Amplitude, they are immediately provisioned with the minimum permissions and added to the group. This means that the user will be sent an email with an invitation.

Refer to this example Group Resource for constructing SCIM requests via PUT or POST and what to expect as a resource from Routes where a resource is returned.

{
  schemas: ['urn:ietf:params:scim:schemas:core:2.0:Group'],
  id: '1',
  displayName: 'Datamonster Party',
  members: [
    { value: '[email protected]', display: 'Data Monster' },
    { value: '[email protected]', display: 'Data Nommer' },
  ],
  meta: {
    resourceType: 'Group',
    created: '2014-01-01T00:00:00.000Z',
    lastModified: '2018-01-01T00:00:00.000Z',
  }
 }