On this page

SCIM API

Regions

The base URL depends on your organization's data residency. In all examples on this page, use the default base URL unless your organization uses Amplitude's EU data center—in that case use the EU base URL in this table.

This API uses core.amplitude.com (default) or core.eu.amplitude.com (EU). Event ingestion uses api2.amplitude.com or api.amplitude.com; other products use their own API hosts as documented. The https://analytics.amplitude.com hostname is the Analytics web app (browser UI), not this API endpoint.

Data residencyBase URL
Defaulthttps://core.amplitude.com
EUhttps://core.eu.amplitude.com

Form all routes against this base URL according to the SCIM Standard. The URL doesn't change between organizations within a region, because the SCIM key used in authentication determines which organization receives the request.

Considerations

Note the following items when configuring the SCIM API integration.

Postman collection

For more examples and to test API requests, refer to the SCIM API Postman collection.

Route version

Although the route includes "1", Amplitude doesn't implement the SCIM 1.1 Standard. The "1" denotes the Amplitude version of this implementation, which future-proofs the API for new iterations 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 for user management.

About users

  • Amplitude defines users as active regardless of whether they have accepted the invitation and logged in to the organization. This setting 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 AttributeNotes
userNamePrimary user email address.
idPrimary user email address.
emailsAmplitude supports one email address per user currently.
name.givenNamePrepended to familyName to create the display name.
name.familyNameappended to givenName to create display name within Amplitude.
activeTrue 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.

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

Query parameters

NameDescription
startIndexOptional. Integer. Defaults to 1. 1-indexed.
itemsPerPageOptional. Integer. Defaults to 100. 100 is the maximum page size.
filterString. Must follow the SCIM filter syntax

Response

A successful request returns a JSON response with user data.

json
{
  "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 user by ID

GET /Users/:id

Gets a user by their ID.

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

Path variables

NameDescription
idRequired. Must be a valid email address. Not case sensitive.

Response

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

json
{
  "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"
  }
}

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.

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

bash
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.

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 already have an invitation 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), Amplitude revokes the invitation.

bash
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", #[tl! ~~]
        "familyName": "Monster"
    },
    "emails": [{
        "primary": true,
        "value": "datamonster@amplitude.com"
    }],
    "active": true,
    "groups": [],
    "meta": {
        "resourceType": "User"
    }
}

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 already have an invitation to Amplitude.

If you delete a pending user (an invited user that hasn't accepted the invitation), Amplitude revokes the invitation.

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

Path variables

NameDescription
idRequired. 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 APIs. Amplitude supports all core fields of the Group Schema. Users within groups are returned with the fields listed in supported user fields.

Get groups

bash
GET /scim/1/Groups HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {scim-token}
json
{
  "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 group by ID

Returns the Amplitude group with the given numeric ID.

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

Path variables

NameDescription
idRequired. Integer. The group ID

Example response

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

json
{
  "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"
  }
}

Create a group

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

When you add a user to a group without first inviting them to the Amplitude organization, Amplitude provisions the user with the minimum permissions and adds them to the group. Amplitude sends the user an email invitation. Learn more about permission groups.

bash
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.

json
{
  "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"
  }
}

Update a user group

Use PATCH requests to add or remove users from a group. The Operations array supports add and remove operations.

bash
PATCH /scim/1/Groups/632 HTTP/1.1
Host: core.amplitude.com
Authorization: Bearer {scim-token}
Content-Type: application/json

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

Example response

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

json
{
  "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

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

Path variables

NameDescription
idRequired. Integer. The group ID

Response

A successful deletion returns a 204 No Content status.

Was this helpful?