API access
Create, rotate and revoke API keys for the current workspace on the API access page, and choose the scopes that each key can use.
An API key lets a script or another tool read your VitalSentinel data, or make changes, through the VitalSentinel API. The account API access page lists the API keys of the current workspace and lets owners and admins create new ones.
Before you start
- To open the page, click your avatar at the top right, click User settings, and then click API access in the API group of the sidebar.
- API keys belong to the current workspace. To see the keys of another workspace, switch the workspace with the switcher at the top of the sidebar.
- Only owners and admins can create, rotate and revoke keys. A member sees only the keys they created.
- Each request with a key spends API credits of the workspace. See API credits.
- For developer details, see Authentication and Scopes.
Live keys
The Live keys card lists the keys that still work, with their count. A member sees the card as Your live keys. Each row shows:
- The key name and its status chip.
- The scopes of the key, as chips.
- Created by and the date, Last used with the date and time, and Expires with the date, if the key expires.
- Restricted to and the number of IP addresses, if the key has an IP allowlist.
- Rotate and Revoke buttons for owners and admins. Rotate shows on Active and Expiring soon keys. A key In grace period shows only Revoke.
Key status
| Status | Meaning |
|---|---|
| Active | The key works. |
| Expiring soon | The key works, but its expiry date is close. |
| In grace period | A newer key replaced this key. This key works until the end of the grace window. |
| Superseded | A newer key replaced this key, and the grace window ended. |
| Expired | The expiry date has passed. |
| Revoked | Somebody revoked the key. |
A key that our team set up for a data export also shows the chip Export key – no credits. You cannot set this chip yourself. See Export keys.
Keys that can change settings
A live key can have scopes of all three levels: Read, Configure and Run. The page then shows a note that names the key. An example is "Reporting script can change settings and start runs". The note ends with "If a tool only needs to read data, give it a read-only key and revoke this one."
Revoked, expired and replaced keys
The Revoked, expired and replaced card lists keys that no longer work. VitalSentinel keeps them on the page so you can see which keys were retired. Each row shows Had access to these scopes and the scopes of the key.
Create an API key
- Click New key, or Create API key if the workspace has no keys.
- In Name, enter a name that tells you where you use the key, for example "Reporting script".
- Optional: in Expires (optional), select a date. Leave it empty for a key that never expires.
- In Scopes, select the scopes that the key needs.
- Optional: in IP allowlist (optional), enter an IP address or range and click Add. Do this for each address.
- Click Create key.
The dialog Save your API key secret then shows the secret of the key. This is the only time that the full secret shows. Click Copy and keep the secret in a safe place. Then click I've saved it – close this.
Copy the secret before you close the dialog. Anybody who has the secret can use the key.
Scopes
A scope gives the key access to one part of VitalSentinel, for example Uptime Monitoring or Google Search Console. The Scopes list puts the scopes into three levels:
| Level | What the key can do |
|---|---|
| Read | Read data and settings. |
| Configure | Change settings. |
| Run | Start runs, for example a new check. |
Each level has an All / None control. Select all and Clear all select or clear every scope. Select only the scopes that the tool needs. For the full list of scopes, see Scopes.
IP allowlist
If you add IP addresses to the IP allowlist (optional), VitalSentinel accepts requests with the key only from these addresses or ranges. Enter one IP address, such as 203.0.113.4, or one range, such as 203.0.113.0/24. Leave the list empty to allow any IP address.
Rotate an API key
Rotate a key to get a new secret and stop the old secret.
- On the row of the key, click Rotate.
- In Grace window, select how long the old secret keeps working: No grace period – the old secret stops working immediately, 1 hour, 24 hours (recommended), 3 days or 7 days.
- Click Rotate key.
- Copy the new secret.
- Put the new secret in every tool that used the old key.
During the grace window, the old key shows In grace period and "Replaced by a newer key."
Revoke an API key
Revoking is permanent. Every tool that uses the key fails on its next request, with no grace window. To get access again, create a new key and update every tool. If you need a grace window, use Rotate instead.
- On the row of the key, click Revoke.
- Click Revoke key.
The message API key revoked confirms it.
Troubleshooting
Why can I not create an API key?
If you are a member, the New key button does not show. If you have no keys, the page says "You have not created any API keys in this workspace. An owner or admin can create one." Ask an owner or admin to create the key, or to make you an admin.
Why does my API key not work?
Look at the status chip of the key. If it is Expired, Revoked or Superseded, create a new key. If the key has an IP allowlist, make sure that the request comes from an allowed address. If the workspace has no API credits left, wait for the next cycle. See API credits.
I lost the secret of my key. What do I do?
VitalSentinel shows the secret only once and cannot show it again. Click Rotate to get a new secret. The new key keeps the name, the scopes and the IP allowlist of the old key. If you are a member, ask an owner or admin to rotate the key.
Why do I not see the keys of my other workspace?
API keys belong to one workspace. Switch the workspace with the switcher at the top of the settings sidebar.
Related
- Connected apps - apps that you allowed to act for you
- Data access log - every request that a key made
- API introduction - get started with the API
- MCP introduction - connect an AI assistant
- API authentication - send the key with each request
- Scopes - what each scope allows
