User Management via the API

The Users API allows integrations installed in Enterprise tenants to programmatically manage Benchling users. This includes basic CRUD operations like reading and writing user data, bulk create/update of users, and querying for specific user activity.

If you're new to the Benchling API, be sure to check out the Tutorial in our Overview page before proceeding.

Users API Overview

The Users API includes a number of endpoints for managing Benchling users:

Endpoint	Description
List users	Returns a paginated list of Benchling users. Can filter based on userId and name.
Create a user	Creates a single Benchling user. Accepts a user object including email, handle, and name.
Get a user by ID	Returns a single user by Benchling API ID.
Update a user by ID	Updates a single Benchling users. Supports suspending Benchling users via the `isSuspended` property
Last user activity	Returns activity metadata for a single user by Benchling API ID. Currently limited to `lastSeen` property.
Bulk create users	Creates a number of Benchling users. Accepts an array of user objects, each including email, handle, and name.
Bulk update users	Updates a number of Benchling users. Accepts an array of user objects. Note: Swapping user emails in a single request is not currently possible

Permissions

User management is a highly privileged activity; for this reason, creating and updating Benchling users requires tenant admin privileges. Because apps cannot be made tenant admins, creating and updating Benchling users requires use of an API key generated by a tenant admin.

Reading Benchling user data (e.g. using the List users endpoint) doesn't require any specific privileges, but the users returned depends on their organization membership. An app can only read a user's information if they are both members of the same organization. The same principle applies when using an API key, based on the user who created the key.

1642 — In this example, the App is a member of the Alpha Lab organization. When reading user information, the app only has access to users A, B, C, D, and E.

Suspension

Suspending users can be accomplished using either the single or bulk update endpoints. In the body of user update object, setting the isSuspended property to true will suspend a user. Suspended users still exist on a tenant, but are logged out of Benchling and cannot re-authenticate. For example:

curl -X PUT  https://$YOUR_DOMAIN/api/v2/users/$USERID
	-H "Content-Type: application/json"
	-u $YOUR_API_KEY:
  -d '{"isSuspended": true}'