Overview
The System for Cross-domain Identity Management (SCIM) is a specification designed to make it easier to manage user identities in cloud-based applications and services. By setting up SCIM integration with your Quip site, you can make employee access changes in an identity service (like Okta, Active Directory, or OneLogin), and those changes will propagate to the employees' Quip accounts.
Specifically, that means you can automate the following processes:
- Account Creation: Creating a new employee's corporate credentials through an identity provider triggers the creation of a new Quip account for that employee
- Account Disable: Disabling an employee's corporate credentials through an identity provider automatically triggers the disabling of that employee's Quip account
- Group Membership: SCIM can be used to synchronize group membership between your identity service and Quip.
Quip supports SCIM integration using either version 1.1 or version 2.0 (preferred) of the specification, with some limitations - see Limitations and Known Issues below. Quip decides what version to use based on the request path: paths containing "/2" use version 2.0, while paths containing "/1" or with no version string use version 1.1.
Authentication
Authorization tokens are only available for Quip Enterprise customers.
To get an authorization token, head over to: {yourcompany}.quip.com/business/admin/scim
Note that:
- All requests to the SCIM APIs should include the token in the Authorization header, i.e. "Authorization: Bearer {your token}".
- You'll need to be an administrator of your company's Quip site to access this page.
Limitations and Known Issues
All Versions.
- Per the v2.0 specification, the
userName
field is set by Quip and may not be modified. If a request attempts to specify theuserName
field, that portion of the request will be ignored. If the request would be otherwise successful, or if that was the only modification requested, the request will return as successful. Note that this failure behavior may change in future releases. (When integrating with Active Directory, we have seen AD makePATCH
requests that attempt to update this field. The failure of these requests may cause problems.) - User emails must be unique within each company in the quip system. This includes email addresses assigned to disabled users. If you attempt to create a new user with the same email address as a disabled user in your company, the previously disabled user will be reactivated and any information included in the Create User request will be discarded. Also see How To, below.
- For names, the fields
givenName
,familyName
, andformatted
are not stored as separate fields. The value offormatted
is always the same asgivenName
, followed by a space, followed byfamilyName
. - Groups must have at least one member. Thus, flows where a group is initially created with no members, and members are added on subsequent calls, are not supported. (This may cause issues with Active Directory integration.)
- Groups do not support the
externalId
attribute. GET /Groups
does not support sorting or filtering.
v1.1
- the
PATCH
operation is not supported for the/Users
resource. - nothing in the v1.1 API allows the primary email to be changed. Workaround: v2
PATCH /Users/:userId
can be used to update the primary email.
v2.0
- The
PATCH
operation is not supported for the/Groups
resource. - In
PATCH /2/Users
, paths with expressions are not supported. e.g. nopath: email[value sw foo]
How Tos
This section gives information on how to perform common operations.
Work With Users
To perform any operations on a user, first you will need to know its user ID. This is the unique ID of the user in the Quip system, and it will be different from the ID used in an external system. You can use the Get Users API to do this. Some examples:
- Get all users:
GET /2/Users
- Get ten users:
GET /2/Users?count=10
- Get the next ten users:
GET /2/Users?count=10&startIndex=11
- Get the user with the matching email (will always return a list of 1 or 0):
GET /2/Users?filter=emails+eq+test@hello.com
- Get the user with the matching external ID (will always return a list of 1 or 0):
GET /2/Users?filter=externalid+eq+1234ABCD
Once you have a user ID, you can use the Update User, Patch User, or Disable User Account operation to make changes. See those specific API descriptions for more details.
Disable Active User Sessions
To disable active user sessions, you can call V2 Patch User twice in succession, once to set active
to false
, and again to set active
to true
.
Deal with Duplicate Emails
If there's an existing disabled account that has an email that you want to assign to a new account, because the new person with that email is different from the old, you will need to modify the old account. One way to do this is:
- look for a disabled account with the new email:
GET /2/Users?filter=emails+eq+test@hello.com
- if the response is not an empty list, get the user ID and use a Patch User request against that ID to replace the disabled user's email with a unique but harmless value.