API Keys

The API Keys page allows you to create and manage API keys used to authenticate with the Alerta API. Navigate to it from the main menu under Configuration > API Keys.

Creating an API Key

Click the + button to create a new API key. The following fields are required:

  • Scopes – select one or more scopes to grant to the key. Common choices include read, write, and admin. Fine-grained scopes such as read:alerts, write:alerts, and write:heartbeats are also available.

  • Expires – set an expiry time for the key. Keys can be created with a fixed duration or set to never expire.

  • Text – a free-text description to identify the purpose of the key.

After creation, the full API key value is displayed once. Copy it immediately as it cannot be retrieved again.

Note

Users can only create keys with scopes that are equal to or less than their own permissions. Admin users can create keys with any scope.

Listing API Keys

The API keys table shows all keys you have access to view, with the following columns:

  • Key – a partial view of the key value (last 4 characters)

  • Scopes – the scopes assigned to the key

  • Description – the text description

  • Expires – the expiry date and time

  • Status – active or expired

  • Customer – the customer associated with the key (if applicable)

Admin users can see all API keys. Non-admin users only see their own keys.

Revoking API Keys

Click the delete icon next to a key to revoke it. Revoked keys are immediately invalidated and can no longer be used for API authentication.

Tip

Use read-only scopes (read) for monitoring dashboards and integrations that do not need to modify data. Use write scopes only for tools that need to create or update alerts.