Authentication Methods

There are 3 main ways to authenticate with Benchling's APIs. Read the below sections to get the details on each, or skip to the which one should I use section to figure out which is most relevant!

OAuth Bearer Authentication for Apps

Apps (see Getting Started Benchling Apps for more information on what they are) authenticate with Benchling APIs using an OAuth Bearer token. In short, this means apps follow this general authorization flow:

1. The app calls the /token endpoint using its client ID and client secret
2. The endpoint returns a bearer access_token that has an expiration
3. The app calls all other endpoints using the Bearer token header
4. The app refreshes the token by calling the /token endpoint again when the token expires

Check out the Getting Started with Benchling Apps guide for more detailed information on the exact flow and example calls.

Basic Authentication for Users

Requests made to the API by users are usually authenticated with HTTP Basic authentication.

In order to properly authenticate with the API, you must use your API key as the username while leaving the password blank. Requests not properly authenticated will return a 401 error code. You can generate API keys for your account in your Profile Settings. All API requests must be made over HTTPS.

📘

In curl, you can specify the username with the -u flag - make sure to include a : afterwards, which indicates an empty password.

Note: If you're an Enterprise customer, you'll need to use your company's URL to authenticate (e.g. yourcompany.benchling.com instead of benchling.com).

curl -u sk_YOUR_SECRET_KEY: https://benchling.com/api/v2/plates
# The colon prevents curl from asking for a password.

OpenID Connect (OIDC) Authentication

Benchling for Enterprise supports authenticating with OpenID Connect (OIDC) id tokens. In this configuration, you'll need a trusted identity provider (such as Okta or AD FS) that supports OpenID Connect.

From your application, you can authenticate to the identity provider, which provides an id token in response. Your identity provider should be configured to include "email" as a claim in the token. You can then use the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ID_TOKEN_HERE" https://benchling.com/api/v2/plates

The Benchling API accepts this token by verifying the signature against keys presented at your OpenID configuration endpoint (e.g. at https://example.com/.well-known/openid-configuration). Once the token signature is verified, the API request is authenticated as the user associated with the email claim on the token.

Note that the user must already exist - in most cases this means the user should sign into the web application before making API requests.

While OpenID Authentication is an open standard, it relies on the identity provider complying with the standard to work. To date, we've had clients successfully configure this with the following IdPs:

• Okta
• Azure Active Directory

Contact [email protected] to configure OpenID Authentication.

Which one should I use?

For dedicated integration or automation scripts you create, it's recommended that you use Benchling Apps to differentiate your integration from calls made by an individual. In this case, you should use OAuth Bearer Authentication.

If you are just running a quick test, or are writing a script for an API call that only needs to be made a couple times, you may decide to use Basic Authentication. In this case actions taken will be associated with the user who owns the API key.

OIDC Authentication is best used when an integration needs to authenticate as multiple users rather than taking all actions under a single app. OIDC allows the integration to act as any user that is accessible in the identity provider. This requires extensive setup though and does require you to have an identity provider that supports the standard. If it is not critical for your use case, consider using an app.

Warehouse Authentication

The Benchling Warehouse does not leverage these authentication methods. Check out the Warehouse Overview & Getting Started doc for more information on how to connect to it.

Managing API Permissions

All calls to Benchling's API are tied to a user or app. Essentially, anything a user has permission to do through the UI, the user's API Key or OIDC token or application's OAuth Bearer token has permission to do through the API.

Service Accounts

Benchling apps are intended to function as service accounts. They are granted permissions similarly to individual users. By default, newly created apps do not belong to any organization, teams, or projects and cannot access any data. To give it access to data on your Benchling tenant via the API, you (or the relevant admin) need to add the app to the various organization(s), team(s), and project(s) as needed. See granting an app access for examples of how to do this.

Suspended Users

For calls that are tied to a user, if the user is suspended, their API key will no longer be allowed to call the API.

❗️

Users must be suspended in Benchling

If a user is suspended in your identity provider, it does not automatically suspend that user in Benchling. To invalidate a user's API credentials, you must suspend the user in Benchling's admin console.

If the suspended user had access to an app's credentials, you should likely generate a new client secret for those app(s), as apps are not tied to a specific user and will not be suspended.

If the user is un-suspended, the original key will resume working normally and does not need to be regenerated. This is not true for the Warehouse, which does require un-suspended users to generate a new Warehouse login.

Archived Apps

If an app is archived, it will no longer be able to access the API. Unarchiving it will allow it to resume access without generating a new client secret.