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.
The User Management API follows the SCIM 2.0 Standard, allowing for the creation, retrieval, update, and deletion calls for users (including pending users) and permission groups.
The User Management API is meant to work in tandem with Permission Groups and Enterprise-level Project-Level Permissions, so it is only available for customers on an Enterprise plan. Please reach out to your Customer Success Manager to have these features turned on, as well as to have access to SCIM Provisioning.
If you plan on using SCIM provisioning to integrate with an Identity Provider/SSO solution, ensure that SCIM is also enabled within that tool as well.
Amplitude currently supports all fields of the core Group Schema of SCIM, as well as the following fields in the core User Schema:
|SCIM User Attribute||Special Note|
|userName||equivalent to email|
|givenName||prepended to familyName to create display name|
|familyName||appended to givenName to create display name|
|only one email is allowed|
|active||active is true for invited users as well as joined users|
Enabling SCIM Provisioning in Amplitude
If SCIM Provisioning is available in your organization, it will appear in the "Access and SSO Settings" section of your organization's settings menu, under "Provisioning Settings".
After enabling provisioning, click "Generate SCIM Key" to generate the access token used to authenticate requests for the SCIM API.
Important: For security reasons, the SCIM Key is only available once and will not be surfaced in the product afterwards. If you lose access to the key, click "Regenerate SCIM Key" and keep a record of the new key.
Important: When generating/regenerating the SCIM key, changes are applied immediately and the old key will be rejected from future API calls, even if the other changes on the page have not yet been saved.
Configuring a SCIM Application within Identity Providers
Currently, there is no Amplitude SCIM Application within the Okta Integration Network. For the time being, this guide outlines how to create a custom application to support SCIM provisioning.
Under Applications, add a new Web Application of authentication type "SWA". If you plan on using the application for purely SCIM provisioning and not SWA, the fields in the wizard do not matter but we suggest:
- App's Login Page URL: Your organization's custom login url (ex. for users who want to enter https://analytics.amplitude.com/okta, this would be https://analytics.amplitude.com/login/okta)
After creation, edit the general settings to change the provisioning type to SCIM provisioning.
In the Sign-On tab, switch the Credential Details of the application to Email.
In the Provisioning tab, use these details to complete configuration:
|Okta Provisioning Field||Amplitude-Specific Configuration Value|
|Your SCIM Access Key|
In Okta, our SCIM API provides the following features:
- Import Users/Groups: Accesses the users and groups currently within your organization inside Amplitude, and adds new users or updates existing users within Okta.
- Create New Users: On assignment of a user or group to the application, users will be invited to your organization in Amplitude and be sent an invitation email to complete sign-up.
- Update User Attributes: Used to keep profiles in sync from Okta to Amplitude.
- Deactivate Users: On removal of a user assignment from the Okta application, the users will also be removed from your Amplitude organization.
- Push Groups: Creates new groups in Amplitude and links them to groups within Amplitude.
Troubleshooting and Known Issues
Known Issue: When updating a user's email in Okta, these changes will not reflect in Amplitude.
Known Issue: Users are only asked to input their first and last names upon first sign-up in Amplitude, though they may be invited to an organization before this happens. If Import Users is used while there are pending users that have never been in any Amplitude organization, the SCIM API will place placeholder values for their first and last names (NO_GIVEN_NAME and NO_FAMILY_NAME, respectively).
There can be issues when authenticating an Identity Provider's Application with Amplitude's SCIM API. For example, such errors can occur when testing the SCIM connection within Okta. When such errors happen, try this troubleshooting procedure:
- In your Access and SSO Settings Tab, ensure that SCIM is enabled (remember to save the configuration if this needs to be enabled!)
- Click "Regenerate SCIM Key" and confirm the key regeneration (this will immediately invalidate the old key)
- Copy the new key value and retest the configuration (see our technical guide if you wish to construct your own requests outside of a provider's integration)
For a technical guide and spec for interfacing with the SCIM API, see our SCIM API guide in our developer docs. This is useful for developers testing the SCIM API, developing scripts that call the Amplitude SCIM API, or constructing one-off requests.