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:

1. Account Creation: Creating a new employee's corporate credentials through an identity provider triggers the creation of a new Quip account for that employee
2. Account Disable: Disabling an employee's corporate credentials through an identity provider automatically triggers the disabling of that employee's Quip account
3. Group Membership: SCIM can be used to synchronize group membership between your identity service and Quip.
4. Accounts Merge: Merge one account into another. The account that was merged into the other will be disabled after.

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" use version 1.1.

Operations for SCIM v1.1. For reference, general SCIM v1.1 specifications can be found here:

• Core Schema
• REST API

Operations for SCIM v2.0. For reference, general SCIM v2.0 specifications can be found here:

• Core Schema
• REST API

Quip's APIs have rate limits to help ensure fair and reliable access to APIs for all of our customers.

Quip's APIs are also subject to a per-company rate limit with a default of 600 requests per minute. The API responses include these custom headers to help developers implement backoffs in their code:

• X-Scim-RateLimit-Limit: The number of requests per minute that your company can make
• X-Scim-RateLimit-Remaining: The number of requests remaining for your company within the minute
• X-Scim-RateLimit-Reset: The UTC timestamp for when the rate limit resets
• X-Scim-Retry-After: The number of seconds after which your company can make API calls again

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.

• Per the v2.0 specification, the userName field is set by Quip and may not be modified. If a request attempts to specify the userName 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 make PATCH 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, and formatted are not stored as separate fields. The value of formatted is always the same as givenName, followed by a space, followed by familyName.
• 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.
• The roles field has been deprecated and shouldn’t be used in the SCIM requests. To adjust admin roles for users, please review the Admin API documentation.

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

• The PATCH operation is not supported for the /Groups resource.
• In PATCH /2/Users, paths with expressions are not supported. e.g. no path: email[value sw foo]

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.

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.

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.