13.2Create an API key

Any member of your team can create and revoke keys. You do this in the dashboard.

1. Select secrets in the top navigation, then the api keys tab. The page is part of the secrets & discovery section.
2. Select new key.
3. In name, enter what will use the key, such as github actions.
4. Tick read only if the key only needs to read, as for Prometheus. See Read-only keys below.
5. Select create key, or press Enter.
6. The key appears in a box: "<name> · copy it now, it is not shown again". Select copy.
7. Store the key somewhere safe, such as your CI system's secret settings. Then select done.

The list shows each key's name, the start of the key (obs_ and 6 more characters), the date it was created, and by whom. A read-only key has a read only badge next to its name.

Things to know about keys#

• Every key starts with obs_.
• A key has no expiry date. It works until you revoke it.
• A key has full access or is read-only. There are no other scopes (narrower permissions).
• The name is required and must fit on one line.
• Your team can hold up to 50 keys. From 40 keys, the page shows a warning. At 50, delete a key before you create a new one.
• Actions done with a key are recorded under the key's name. For example, an acknowledged incident shows API key "github actions".

Read-only keys#

A read-only key can read monitors, results and incidents but not change anything. It can call the read RPCs: lists, gets, summaries, series and metrics. Use one for Prometheus (13.10) and other tools that only read. A leaked read-only key cannot pause, change or delete your monitors.

Anything that changes state, such as creating, editing or deleting a monitor or acknowledging an incident, answers permission_denied with the message this API key is read-only.

You choose read-only when you create the key. You cannot change it later. To change a key's access, create a new key and revoke the old one.

The api keys page has a new read-only key button in its scrape with prometheus box. It opens new key with the name prometheus and read only ticked.

Revoke a key#

1. On the api keys tab, select revoke next to the key.
2. Select revoke again to confirm, or no to keep it.

A revoked key stops working within a minute. Revoke a key at once if it may have leaked.

What a key cannot do#

These actions work only in the dashboard. With a key, they answer permission_denied.

• Create, list or revoke API keys.
• Change which sites a secret may be sent to (chapter 8).
• Change your team's paging defaults (9.4). In the dashboard, only a team owner can do this.
• Read the audit log (14.5).
• Change your plan.

Creating, listing or revoking keys, changing allowed sites and reading the audit log give the message an API key cannot do this; sign in to the dashboard. Changing paging defaults gives only a team owner can change its paging defaults (14.3).

A key can read alert channels, but their credentials come back empty. This covers Slack, Teams and Discord webhook URLs, the Telegram bot token, the PagerDuty routing key, the webhook URL and secret, and the values of webhook headers. The header names, emailTo and telegramChatId are returned.