mabl API keys enable programmatic access to the information in your mabl workspace. This guide covers how to create, manage, and rotate API keys. For help choosing a key type, see API key types below.
Note
API key access and usage is limited exclusively to workspace owners.
You can create, pause, unpause, and delete API keys. Visit the APIs page to get started: Settings > APIs.
Creating API keys
To create an API key, workspace owners can navigate to Settings > APIs and take the following steps:
- Click on the + Create API key button to open the Create API Key modal.
- Select the type of API key.
- Give the API key a name.
- Optional: Check the Key expires checkbox and set an expiration time range between 1 and 365 days.
- Click on the Save button.
Note
You can only set an expiration date when creating a new API key. You cannot add an expiration date to an existing key.
The new API key appears on the APIs page, where you can view, copy, pause, unpause, and delete the key as needed.
Rotating API keys
Regularly rotating API keys reduces the risk of compromised credentials.
Rotating with expiration dates
If you set an expiration date when creating a key, the original key automatically stops working when it expires. mabl sends notification emails to workspace owners as the expiration date approaches on the following schedule:
- 7 days before expiration
- 3 days before expiration
- 1 day before expiration
- On the expiration date
Use these notifications as a prompt to rotate the key if it’s still needed, or to confirm that the key is safe to let expire. Once expired, the key stops working automatically. No manual action is required.
To rotate a key using expiration dates:
- Create a new API key of the same type, optionally with a new expiration date.
- Update the consuming integration with the new key value.
- Allow the original key to expire. No further action is needed.
Rotating manually
If the original key doesn’t have an expiration date, you can manually disable it after confirming the new key works:
- Create a new API key of the same type.
- Update the consuming integration with the new API key value.
- Pause the original API key.
- Confirm that the integration works as expected with the new key.
- Delete the original, paused API key.
Pausing API keys
To temporarily disable an API key, toggle it off.
Unpausing API keys
Toggling an API key on instantly re-enables API access for the key.
Removing API keys
Click on the trash icon to permanently remove an API key.
Deleted API key cannot be recovered
Ensure an API key is no longer in use before deleting the key. Once deleted, an API key cannot be restored, meaning any impacted scripts and services will be unable to access mabl. If any clients are using this key, they will no longer be able to access mabl services.
If you are unsure whether any scripts or services are still accessing the API, try pausing the API key first.
API key types
Different API keys are permissioned for different use cases. Keys only have the read/write permissions necessary for a specific use case.
| API key type | Use |
|---|---|
| CI/CD Integration | Use with mabl’s CI/CD integrations, including Jenkins, Bamboo, Microsoft Azure DevOps, GitHub Actions, and Octopus Deploy. |
| Command Line Interface | Use with the mabl CLI. |
| Deployment Trigger | Use to start tests with the Deployment Events API and to retrieve test results with the Execution Result API. |
| Editor | Use to perform actions permitted by the editor role. |
| Issue Tracker | Use with the mabl Jira plugin. |
| Link Agent | Use with the mabl Link agent. |
| Java Selenium Agent | Use with Selenium Java Agent. |
| Usage Analytics | Use with the mabl Segment integration. |
| Viewer | Use for mabl API endpoints that are read-only, such as the Reporting API. |
| Workspace admin | Use for read-write permissions with credentials and Link Agents. |
The Integration key type is deprecated. Existing legacy Integration keys will continue to function, but users cannot create new API keys of this type.