Set up SCIM provisioning in Amplitude
In Amplitude, the User Management API provides a programmatic solution to provisioning and group management through a public API. Use the API to manage organizations at scale and integrate provisioning with other tools, including identity providers.
The User Management API follows the SCIM 2.0 Standard. It supports create, retrieve, update, and delete calls for users, pending users, and permission groups.
For a technical guide and spec for the SCIM API, refer to the SCIM API guide. The guide is useful for developers testing the SCIM API, developing scripts that call the Amplitude SCIM API, or constructing one-off requests.
Before you begin
The User Management API works in tandem with permission groups.
If you plan to use SCIM provisioning to integrate with an identity provider or SSO solution, make sure SCIM is also enabled within that tool.
Enable SCIM provisioning in Amplitude
If your organization includes SCIM provisioning, you can find it in the Access and SSO Settings section of your organization's settings menu, under Provisioning Settings.
Set the Enable SCIM Provisioning toggle to Enabled. Then click Generate SCIM Key to generate the access token used to authenticate requests for the SCIM API.
For security reasons, Amplitude shows the SCIM Key only when you enable it. If you lose access to the key, click Regenerate SCIM Key. Keep a record of the new key. When you generate or regenerate the SCIM key, changes apply immediately and Amplitude rejects the old key from any API calls, even if the other changes on the page aren't saved.
Supported fields
Amplitude supports all fields of the SCIM core group schema and the following fields in the core user schema:
| SCIM user attribute | Special note |
userName | Same as email. |
givenName | Prepended to familyName to create display name. |
familyName | Appended to givenName to create display name. |
email | Allows only one email. |
active | active is true for invited users and joined users. |
Configure a SCIM application with Okta
In Okta, the Amplitude SCIM API provides the following features:
- Import Users/Groups: Accesses the users and groups in your Amplitude organization, then adds new users or updates existing users within Okta.
- Create New Users: On assignment of a user or group to the application, Amplitude invites users to your organization and sends 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, Amplitude removes the users from your Amplitude organization.
- Push Groups: Creates new groups in Amplitude and links them to groups within Amplitude.
Okta integration
The best way to integrate Okta provisioning with Amplitude is with the Amplitude application within the Okta Integration Network. To integrate Okta provisioning:
In the Okta Integration Catalog, navigate to Applications and find the Amplitude application. Use the Org ID available in the General Settings section in Amplitude to create the integration.
After you create the integration, set up and authenticate provisioning calls to Amplitude. Navigate to the Provisioning tab and click Configure API Integration.
Enter the API Token. This token is the same as the SCIM key provided by Amplitude. Enter the token in the field and click Save. You should now have access to user provisioning actions in the Import, Assignment, and Push Groups tabs of the application.
After Okta verifies the connection, select the provisioning actions that Okta can send to Amplitude. Check any features in the To App section of the Provisioning tab that fit your needs. Select all available features when possible, so Amplitude's user records closely match your Okta directory.
Manual configuration (SAML)
If your SSO requires SAML support, use the manual configuration described in Set up single sign-on (SSO) for Amplitude using Okta.
Troubleshooting
Amplitude asks users to provide their first and last names upon first sign-up in Amplitude, though they may receive an invitation to join an organization before first sign-up. If you use Import Users while pending users have never been in any Amplitude organization, the SCIM API uses placeholder values for their first and last names: NO_GIVEN_NAME and NO_FAMILY_NAME.
Authentication issues can occur between an identity provider's application and Amplitude's SCIM API. For example, this can happen when testing the SCIM connection within Okta. To troubleshoot SCIM authentication:
- In your Access and SSO Settings tab, ensure that you enable SCIM. Save the configuration if you enable SCIM.
- Click Regenerate SCIM Key and confirm the key regeneration. This immediately invalidates the old key.
- Copy the new key value and retest the configuration. To construct your own requests outside of a provider's integration, refer to the SCIM API guide.
Was this helpful?