Skip to content

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 the Help Center Guide.

Get more examples for this API

The Amplitude Developers Postman profile has a full library of example requests and responses for this API.

Check out the Amplitude Developers Profile to view the collection. You don't need a Postman account to browse.

If you already use Postman, you can fork and run this collection in Postman.

Authorization

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 the Help Center Guide for a detailed guide on how to find and save this key.

Example request header:

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

Considerations

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.

Important notes 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

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

GET /scim/1/Users HTTP/1.1
Host: core.amplitude.com
Authorization: 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.

{
    "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": "datamonster@amplitude.com",
            "userName": "datamonster@amplitude.com",
            "name": {
                "givenName": "data",
                "familyName": "monster"
            },
            "active": true,
            "emails": [
                {
                    "value": "datamonster@amplitude.com",
                    "primary": true
                }
            ],
            "meta": {
                "resourceType": "User"
            }
        }
    ]
}

GET /Users/:id

Gets a user by ID.

GET /scim/1/Users/datamonster@amplitude.com HTTP/1.1
Host: core.amplitude.com
Authorization: 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.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "datamonster@amplitude.com",
    "userName": "datamonster@amplitude.com",
    "name": {
        "givenName": "Data",
        "familyName": "Monster"
    },
    "active": true,
    "emails": [
        {
            "primary": true,
            "value": "datamonster@amplitude.com"
        }
    ],
    "groups": [],
    "meta": {
        "resourceType": "User"
    }
}

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.

Example request

POST /scim/1/Users/ HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {{scim-token}}
Content-Type: application/json
Content-Length: 364

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "id":"<USER EMAIL>",
   "userName":"<USER EMAIL>",
   "name":{
      "givenName":"<USER GIVEN NAME>",
      "familyName":"<USER FAMILY NAME>"
   },
   "emails":[
      {
         "value":"<USER EMAIL>",
         "primary":true
      }
   ],
   "meta":{
      "resourceType":"User"
   }
}

Request body

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

Response

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

PUT /Users/:id and 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.

Example requests

In this example, update the user's given name. 

PUT /scim/1/Users/datamonster@amplitude.com HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {{scim-token}}
Content-Length: 423

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "datamonster@amplitude.com",
    "userName": "datamonster@amplitude.com",
    "name": {
        "givenName": "Datamonster",
        "familyName": "Monster"
    },
    "emails": [{
        "primary": true,
        "value": "datamonster@amplitude.com"
    }],
    "active": true,
    "groups": [],
    "meta": {
        "resourceType": "User"
    }
}

In this example, you update active to false and deactivate the user. 

PUT /scim/1/Users/datamonster@amplitude.com HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {{scim-token}}
Content-Length: 424

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "datamonster@amplitude.com",
    "userName": "datamonster@amplitude.com",
    "name": {
        "givenName": "Datamonster",
        "familyName": "Monster"
    },
    "emails": [{
        "primary": true,
        "value": "datamonster@amplitude.com"
    }],
    "active": false,
    "groups": [],
    "meta": {
        "resourceType": "User"
    }
}

Response

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

DELETE /Users/:id

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.

Path variables

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

Example request

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

User response

A successful delete request returns a 204 No Content response.

Group routes

Info

Permission groups are available in Enterprise accounts.

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.

Group route methods

Get more examples for this API

The Amplitude Developers Postman profile has a full library of example requests and responses for this API.

Check out the Amplitude Developers Profile to view the collection. You don't need a Postman account to browse.

If you already use Postman, you can fork and run this collection in Postman.

GET /Groups

Returns all active groups.

Example request

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

Example response

A successful request returns a JSON response with group data.

{
    "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:Group"
            ],
            "id": 632,
            "displayName": "Datamonster Party",
            "members": [
                {
                    "value": "data.engineer@amplitude.com",
                    "display": "data nommer"
                },
                {
                    "value": "datamonster@amplitude.com",
                    "display": "data monster"
                }
            ],
            "meta": {
                "resourceType": "Group",
                "created": "2022-02-03T20:40:22.000+00:00",
                "lastModified": "2022-02-03T20:40:22.000+00:00"
            }
        }
    ]
}

GET /Groups/:id

Returns the Amplitude group with the given numeric ID.

Example request

GET /scim/1/Groups/632 HTTP/1.1
Host: core.amplitude.com
Authorization: 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.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "632",
    "displayName": "Datamonster Party",
    "members": [
        {
            "value": "data.engineer@amplitude.com",
            "display": "Data Engineer"
        },
        {
            "value": "datamonster@amplitude.com",
            "display": "data monster"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2022-02-03T20:40:22.000+00:00",
        "lastModified": "2022-02-03T20:40:22.000+00:00"
    }
}

POST /Groups/

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 in the Help Center.

Example request

Send a request that includes the group name and members.

POST /scim/1/Groups HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {{scim-token}}
Content-Type: application/json
Content-Length: 265

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:Group"
   ],
   "displayName":"Group Name",
   "members":[
      {
         "value":"datamonster@amplitude.com"
      },
      {
         "value":"developerdocs@amplitude.com"
      }
   ]
}

Response

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

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": 671,
    "displayName": "Group Name",
    "members": [
        {
            "value": "datamonster@amplitude.com",
            "display": "data monster"
        },
        {
            "value": "developerdocs@amplitude.com",
            "display": "undefined undefined"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2022-03-03T20:38:36.000+00:00",
        "lastModified": "2022-03-03T20:38:36.000+00:00"
    }
}

PATCH /Groups/:id

Updates an Amplitude group by specifying field on a Group to update.

Example request

PATCH /scim/1/Groups/632 HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {{scim-token}}
Content-Length: 241

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
          "op": "add",
          "path": "members",
          "value": [{
              "value": "new.member@amplitude.com"
        }]
    }]
}

Path variables

Name Description
id Required. Integer. The group ID

Example response

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

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "632",
    "displayName": "New Name",
    "members": [
        {
            "value": "data.engineer@amplitude.com",
            "display": "data engineer"
        },
        {
            "value": "datamonster@amplitude.com",
            "display": "data monster"
        },
        {
            "value": "new.member@amplitude.com",
            "display": "New Member"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2022-02-03T20:40:22.000+00:00",
        "lastModified": "2022-02-03T21:25:25.000+00:00"
    }
}

DELETE /Groups/:id

Deletes an Amplitude group.

Example request

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

Path variables

Name Description
id Required. Integer. The group ID

Response

A successful deletions returns a 204 No Content status.

Was this page helpful?