API Keys
Create and manage API keys to authenticate the ElemBio CLI and API and create programmatic integrations.
An API key authenticates an application or a user to the ElemBio CLI and API. Use a key with either interface to give scripts or external tools access to your data, for example, to automate downloads or feed an analysis pipeline. Scope each key to only the permissions the integration needs.
In ElemBio Cloud, the API Keys page is available at Organization > API Keys. It contains two tabs:
- API Keys: keys that you create and manage on this page.
- Temporary Download Keys: keys that ElemBio Cloud generates automatically when you download data with the ElemBio CLI. For more information, see Temporary download keys.
Only administrators can create and delete API keys.
API key properties
The API Keys tab lists each key with the following columns:
| Column | Description |
|---|---|
| Name | The unique name you assigned to the key. |
| Description | The optional description of the key, or -- if none was provided. |
| Key | The masked token. Only the last few characters are shown, prefixed with ****. The full token is only displayed at time of creation. |
| Permissions | The permissions granted to the key, such as Runs:Read or Storage:Download. |
| Created | The date the key was created. |
| Last Used | The date the key was last used to authenticate. |
| Expires | The date the key expires. |
| Status | Active or Expired. A key is shown as Expired once it passes its expiration date. |
| Actions | A Delete button for the key. |
Permissions
When you create a key, you grant it one or more permissions by applying scopes to the key. Each permission group (e.g., runs) has a parent permission that grants unrestricted access and granular child permissions that limit access to specific actions. Selecting a parent permission automatically includes all of its child permissions.
When you create an API key with the permission group level, any future scopes that are released will be granted to that api key automatically. Grant the narrowest set of permissions that is required for how you intend to use the API key. For example, for a key that only downloads run files, select Runs > Download rather than the full Runs permission.
| Permission Group | Scope | Grants |
|---|---|---|
| Runs | Runs | Unrestricted access to all run data, including read, download, edit, and all other actions. |
| Read | List and get run metadata for all runs. | |
| Download | Browse and download run files for all runs. | |
| Executions | Executions | Unrestricted access to all analysis executions, including read, download, edit, and all other actions. |
| Read | List and get executions metadata for all executions. | |
| Download | Browse and download executions files for all executions. | |
| Logs | View logs for all executions. | |
| Instruments | Instruments | Unrestricted access to all instrument metadata. |
| Read | List and get instrument metadata for all instruments. | |
| Storage | Storage | Unrestricted access to all storage connections and data. |
| Read | List and get storage metadata for all storage connections. | |
| Download | Browse and download storage files for all storage connections. |
API key security
Treat API keys like passwords. When you create an API key, grant only the scopes required for your integration. Avoid creating broadly scoped keys unless they are necessary.
To help protect your account:
- Follow the principle of least privilege by granting only the permissions your application requires.
- Never commit API keys to source control or include them in client-side code.
- Store API keys securely, such as in environment variables, a secrets manager, or a secure key vault.
- Rotate API keys periodically and immediately if you suspect they have been exposed.
- Delete API keys that are no longer in use.
Create an API key
-
Go to Organization > API Keys.
-
Select Add API Key.
-
In the Name field, enter a unique name for the key. The name can be up to 256 characters.
-
In the Description field, optionally describe what the key is used for. The description can be up to 500 characters.
-
In the Expires In (days) field, enter the number of days until the key expires, from 1 to 365. The default is 30. Keys expire and must be regenerated after this period.
-
Under Permissions, select at least one permission for the key.
-
Select Generate Key.
ElemBio Cloud displays the full API key one time on the Generated API Key screen.
-
Select Copy to copy the key to your clipboard, or select Save and Copy to copy the key and return to the API Keys page.
Copy your API key before you leave the Generated API Key screen. You cannot access the full key again after you navigate away. For security, store the key in a secure location and do not share it.
Delete an API key
Deleting a key immediately revokes it. Any application or script that uses the key can no longer authenticate. This action cannot be undone.
- Go to Organization > API Keys.
- In the Actions column for the key you want to remove, select Delete.
- When prompted, type the exact name of the key to confirm.
- Select Delete.
The key is immediately deleted. Connected integrations using the key will no longer be functional.
Temporary download keys
ElemBio Cloud generates a temporary download key when you choose Download with ElemBio CLI in a file browser, for example, when downloading a run or execution directory. These keys are visible for management purposes in the API Key list. These keys have the following characteristics:
- They are scoped to the specific resource you are downloading.
- They expire after 30 days.
- They appear on the Temporary Download Keys tab, not the API Keys tab.
To revoke a temporary download key before it expires, delete it from the Temporary Download Keys tab using the same delete steps.