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:
SCIM User Attribute | Additional Notes |
---|---|
| Equivalent to the primary email |
| Equivalent to the primary email |
| Amplitude only supports one email per user currently. |
| Prepended to familyName to create the display name |
| appended to givenName to create display name within Amplitude |
| True for pending users as well as joined users |
GET /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 |
---|---|---|---|
| Integer | 1 | 1-indexed |
| Integer | 100 | Can be overriden to be higher |
| 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
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
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
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
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
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 |
---|---|---|
|
| Returns all active groups for this organization within Amplitude |
|
| Returns a single group with the given numeric ID within Amplitude. |
|
| Creates a group within Amplitude, adding users to the group and inviting any users not present within Amplitude already |
|
| Updates a group within Amplitude, adding and removing users as necessary. |
|
| Updates a group within Amplitude through specifying specific field on a Group to modify. Compared to |
|
| 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 11 months ago