Requests made to the API 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.
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
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:
- Azure Active Directory
Contact [email protected] to configure OpenID Authentication.
The majority of users of the Benchling API leverage the basic authentication method, as it provides the most straightforward method. This is the best path forward for most use cases.
OIDC Authentication is best used when an integration needs to authenticate as multiple users rather than taking all actions under a single user. OIDC allows the integration to act as any user that it can access in the identity provider.
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.
All calls to Benchling's API are tied to a user. Essentially, anything the user has permission to do through the UI, the user's API key (or OIDC token) has permission to do through the API.
Typically, an admin will use their API key for integrations that they manage. This is the simplest solution, and is straightforward for a very small number of integrations or one-off scripts, but it can become unwieldy with long running integrations.
You may want to have authentication keys that are dedicated to specific tasks and permissioned independently from an active Benchling user. Benchling does not have a separate account type for this, but rather leverages regular user accounts. To set up this kind of dedicated access in Benchling, you can create additional Benchling accounts and grant them API access.
They are still user accounts like any other, and you must log into them through the UI to retrieve their associated API key. This gives you full access to our permissioning system to control access and scope the API key (or OIDC token) to a specific task.
When setting up these accounts, ensure that the email associated with them will still be routed to someone who is able to respond to relevant email notifications from Benchling.
Since all calls are tied to a user, if a 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 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.
Updated 8 days ago