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:

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


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.


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.


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"
  -d '{"isSuspended": true}'