The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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:

SCIM User Attribute

Additional Notes

userName

Equivalent to the primary email

id

Equivalent to the primary email

emails

Amplitude only supports one email per user currently.

name.givenName

Prepended to familyName to create the display name

name.familyName

appended to givenName to create display name within Amplitude

active

True for pending users as well as joined users

GET /Users

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

Query Parameter

Type

Default Value

Additional Notes

startIndex

Integer

1

1-indexed

itemsPerPage

Integer

100

Can be overriden to be higher

filter

String

N/A

Should follow the SCIM filter syntax

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.

Request Method

Route

Description

GET

/Groups/

Returns all active groups for this organization within Amplitude

GET

/Groups/:id

Returns a single group with the given numeric ID within Amplitude.

POST

/Groups/

Creates a group within Amplitude, adding users to the group and inviting any users not present within Amplitude already

PUT

/Groups/:id

Updates a group within Amplitude, adding and removing users as necessary.

PATCH

/Groups/:id

Updates a group within Amplitude through specifying specific field on a Group to modify. Compared to PUT, safer and recommended.

DELETE

/Groups/:id

Deletes a group within Amplitude

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',
  }
 }

Updated 2 months ago


SCIM API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.