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 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 System for Cross-domain Identity Management (SCIM) 2.0 Standard. This guide pays specific attention to any details useful for debugging issues with a SCIM integration.

For help integrating the SCIM API with an Identity Provider like Okta or JumpCloud, or help enabling the SCIM API for an Amplitude organization, see Set up SCIM provisioning in Amplitude.

Authentication

Authorize by sending a Bearer Token in the Authorization Header. The token should equal the key that's generated on the Access and SSO page in the Settings Tab of Amplitude. See Set up SCIM provisioning in Amplitude for a detailed guide on how to find and save this key.

For more information, see Find your API Credentials

Endpoints

Region	Endpoint
Standard server	`https://core.amplitude.com/scim/1/`

Considerations

Keep the following in mind as you configure the SCIM API integration.

Base URL

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

Although the route includes "1", this doesn't mean that Amplitude implements the SCIM 1.1 Standard. This is to denote the Amplitude version of this implementation, future-proofing for new iterations of the API that introduce breaking changes without disrupting service for current consumers.

API usage limits

The SCIM API supports 100 requests per minute per organization. Amplitude can lift this restriction for burst requests on a per-request basis. Contact the support team or a customer success manager for more information.

User routes

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

About users

Users are defined as active within Amplitude regardless of whether they have accepted the invitation and have logged in once to the organization within Amplitude. This prevents Identity Providers from resending invitations to invited and pending users.
The SCIM API sends users created through the POST route an email invitation to complete sign up.

Supported user fields

Amplitude supports the following fields in the core User Schema:

SCIM User Attribute	Notes
`userName`	Primary user email address.
`id`	Primary user email address.
`emails`	Amplitude supports one email address 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 and 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.

1GET /scim/1/Users HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer {scim-token}

Query parameters

Name	Description
`startIndex`	Optional. Integer. Defaults to 1. 1-indexed.
`itemsPerPage`	Optional. Integer. Defaults to 100. 100 is the maximum page size.
`filter`	String. Must follow the SCIM filter syntax

Response

A successful request returns a JSON response with user data.

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 4    ],
 5    "startIndex": 1,
 6    "itemsPerPage": 100,
 7    "totalResults": 1,
 8    "Resources": [
 9        {
10            "schemas": [
11                "urn:ietf:params:scim:schemas:core:2.0:User"
12            ],
13            "id": "datamonster@amplitude.com",
14            "userName": "datamonster@amplitude.com",
15            "name": {
16                "givenName": "data",
17                "familyName": "monster"
18            },
19            "active": true,
20            "emails": [
21                {
22                    "value": "datamonster@amplitude.com",
23                    "primary": true
24                }
25            ],
26            "meta": {
27                "resourceType": "User"
28            }
29        }
30    ]
31}

Get user by ID

GET /Users/:id

Gets a user by their ID.

1GET /scim/1/Users/datamonster@amplitude.com HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer {scim-token}

Path variables

Name	Description
`id`	Required. Must be a valid email address. Not case sensitive.

Response

A successful request returns a JSON response with the user's data.

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:schemas:core:2.0:User"
 4    ],
 5    "id": "datamonster@amplitude.com",
 6    "userName": "datamonster@amplitude.com",
 7    "name": {
 8        "givenName": "Data",
 9        "familyName": "Monster"
10    },
11    "active": true,
12    "emails": [
13        {
14            "primary": true,
15            "value": "datamonster@amplitude.com"
16        }
17    ],
18    "groups": [],
19    "meta": {
20        "resourceType": "User"
21    }
22}

Create users

POST /Users

A POST request creates a new user in Amplitude. This operation sends an invitation link to the email address.

To succeed, id and userName must be valid emails, and the user can't already exist or have a pending invite to your Amplitude organization.

The request body for the POST route should be a valid SCIM User Resource.

Note

The API ignores the Groups field on user routes. To add a user to a group, make a request to the group API routes.

 1POST /scim/1/Users/ HTTP/1.1
 2Host: core.amplitude.com
 3Authorization: Bearer {scim-token}
 4Content-Type: application/json
 5Content-Length: 364
 6 
 7{
 8   "schemas":[
 9      "urn:ietf:params:scim:schemas:core:2.0:User"
10   ],
11   "id":"<USER EMAIL>",
12   "userName":"<USER EMAIL>",
13   "name":{
14      "givenName":"<USER GIVEN NAME>",
15      "familyName":"<USER FAMILY NAME>"
16   },
17   "emails":[
18      {
19         "value":"<USER EMAIL>",
20         "primary":true
21      }
22   ],
23   "meta":{
24      "resourceType":"User"
25   }
26}

Request body

See supported user fields for this request's body parameters.

Response

A successful request returns 201 Created and the original request body.

Update users

PUT /Users/:id or PATCH /Users/:id

Updates the Amplitude user with the given ID. id must be a valid email address, and the user must have already been invited to Amplitude. You can't change the email address.

Setting the active schema field to false in the request body removes the user from the organization, and the user loses all access. If the user is pending (an invited user that hasn't accepted the invitation), the invitation is revoked.

 1PUT /scim/1/Users/datamonster@amplitude.com HTTP/1.1
 2Host: core.amplitude.com
 3Authorization: Bearer {scim-token}
 4Content-Length: 423
 5 
 6{
 7    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
 8    "id": "datamonster@amplitude.com",
 9    "userName": "datamonster@amplitude.com",
10    "name": {
11        "givenName": "Datamonster", 
12        "familyName": "Monster"
13    },
14    "emails": [{
15        "primary": true,
16        "value": "datamonster@amplitude.com"
17    }],
18    "active": true,
19    "groups": [],
20    "meta": {
21        "resourceType": "User"
22    }
23}

 1PUT /scim/1/Users/datamonster@amplitude.com HTTP/1.1
 2Host: core.amplitude.com
 3Authorization: Bearer {scim-token}
 4Content-Length: 424
 5 
 6{
 7    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
 8    "id": "datamonster@amplitude.com",
 9    "userName": "datamonster@amplitude.com",
10    "name": {
11        "givenName": "Datamonster",
12        "familyName": "Monster"
13    },
14    "emails": [{
15        "primary": true,
16        "value": "datamonster@amplitude.com"
17    }],
18    "active": false, 
19    "groups": [],
20    "meta": {
21        "resourceType": "User"
22    }
23}

Response

A successful request returns a 200 OK status and the original request body.

Delete a user

Deletes the Amplitude user with the given ID. The ID must be a valid email, and the user must have been invited to Amplitude already.

If a pending user (an invited user that hasn't accepted the invitation) is deleted, the invitation is revoked.

1DELETE /scim/1/Users/datamonster@amplitude.com HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer {scim-token}

Path variables

Name	Description
`id`	Required. Must be a valid email address. Not case sensitive.

User response

A successful delete request returns a 204 No Content response.

Group routes

This section details the requests available for Permission Group related APIs. Amplitude supports all core fields of the Group Schema, with users within groups returned with the fields listed in supported user fields.

Get groups

1GET /scim/1/Groups HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer {scim-token}

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 4    ],
 5    "startIndex": 1,
 6    "itemsPerPage": 100,
 7    "totalResults": 1,
 8    "Resources": [
 9        {
10            "schemas": [
11                "urn:ietf:params:scim:schemas:core:2.0:Group"
12            ],
13            "id": 632,
14            "displayName": "Datamonster Party",
15            "members": [
16                {
17                    "value": "data.engineer@amplitude.com",
18                    "display": "data nommer"
19                },
20                {
21                    "value": "datamonster@amplitude.com",
22                    "display": "data monster"
23                }
24            ],
25            "meta": {
26                "resourceType": "Group",
27                "created": "2022-02-03T20:40:22.000+00:00",
28                "lastModified": "2022-02-03T20:40:22.000+00:00"
29            }
30        }
31    ]
32}

Get group by ID

Returns the Amplitude group with the given numeric ID.

1GET /scim/1/Groups/632 HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer {scim-token}

Path variables

Name	Description
`id`	Required. Integer. The group ID

Example response

A successful request returns a 200 OK status and a JSON response with data about the group.

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:schemas:core:2.0:Group"
 4    ],
 5    "id": "632",
 6    "displayName": "Datamonster Party",
 7    "members": [
 8        {
 9            "value": "data.engineer@amplitude.com",
10            "display": "Data Engineer"
11        },
12        {
13            "value": "datamonster@amplitude.com",
14            "display": "data monster"
15        }
16    ],
17    "meta": {
18        "resourceType": "Group",
19        "created": "2022-02-03T20:40:22.000+00:00",
20        "lastModified": "2022-02-03T20:40:22.000+00:00"
21    }
22}

Create a group

Creates a group in Amplitude. It adds existing users to the group and invites new users to Amplitude.

Warning

When a user is added to a group without first being invited to the Amplitude organization, they are immediately provisioned with the minimum permissions and added to the group. The user is invited via email. Learn more about permission groups.

 1POST /scim/1/Groups HTTP/1.1
 2Host: core.amplitude.com
 3Authorization: Bearer {scim-token}
 4Content-Type: application/json
 5Content-Length: 265
 6 
 7{
 8   "schemas":[
 9      "urn:ietf:params:scim:schemas:core:2.0:Group"
10   ],
11   "displayName":"Group Name",
12   "members":[
13      {
14         "value":"datamonster@amplitude.com"
15      },
16      {
17         "value":"developerdocs@amplitude.com"
18      }
19   ]
20}

Response

A successful request returns a 200 OK status and JSON body with the group's data.

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:schemas:core:2.0:Group"
 4    ],
 5    "id": 671,
 6    "displayName": "Group Name",
 7    "members": [
 8        {
 9            "value": "datamonster@amplitude.com",
10            "display": "data monster"
11        },
12        {
13            "value": "developerdocs@amplitude.com",
14            "display": "undefined undefined"
15        }
16    ],
17    "meta": {
18        "resourceType": "Group",
19        "created": "2022-03-03T20:38:36.000+00:00",
20        "lastModified": "2022-03-03T20:38:36.000+00:00"
21    }
22}

Update a user group

 1PATCH /scim/1/Groups/632 HTTP/1.1
 2Host: core.amplitude.com
 3Authorization: Bearer {scim-token}
 4Content-Length: 241
 5 
 6{
 7    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 8    "Operations": [
 9        {
10          "op": "add",
11          "path": "members",
12          "value": [{
13              "value": "new.member@amplitude.com"
14        }]
15    }]
16}

Example response

A successful request returns a 200 OK status with a JSON response with the updated group's new data.

 1{
 2    "schemas": [
 3        "urn:ietf:params:scim:schemas:core:2.0:Group"
 4    ],
 5    "id": "632",
 6    "displayName": "New Name",
 7    "members": [
 8        {
 9            "value": "data.engineer@amplitude.com",
10            "display": "data engineer"
11        },
12        {
13            "value": "datamonster@amplitude.com",
14            "display": "data monster"
15        },
16        {
17            "value": "new.member@amplitude.com",
18            "display": "New Member"
19        }
20    ],
21    "meta": {
22        "resourceType": "Group",
23        "created": "2022-02-03T20:40:22.000+00:00",
24        "lastModified": "2022-02-03T21:25:25.000+00:00"
25    }
26}

`DELETE /Groups/:id`

Deletes an Amplitude group.

Example request

1DELETE /scim/1/Groups/632 HTTP/1.1
2Host: core.amplitude.com
3Authorization: Bearer

Path variables

Name	Description
`id`	Required. Integer. The group ID

Response

A successful deletions returns a 204 No Content status.