API keys

API keys authenticate scripts, CI jobs, the local akmcp binary, and anything else that talks to the HTTP API without a browser session. Heartbeat pings do not need one - the ping URL carries its own key - and the hosted Claude connector uses OAuth instead.

Create a key

Settings, then API Keys. Give the key a name (up to 100 characters, usually the system that will hold it) and choose an expiry: No expiry, 1 day, 7 days, 30 days, 90 days, or Custom with a date. The key is shown once:

API key created successfully. Copy this key now - you will not be able to see it again.

Only the last four characters are stored for display afterwards. Keys look like ak. followed by a random identifier. Each user can hold up to 25 active keys.

Use a key

Send it in the X-API-Key header:

curl -H "X-API-Key: ak.your_key_here" \
  https://your-team.alertkick.com/api/v1/alerts

The base URL is your workspace, https://<subdomain>.alertkick.com. A key is bound to that workspace; sending it to another subdomain returns 401 API Key is not valid for this subdomain.

A key acts as the user who created it and inherits that user’s role. There are no per-key scopes, so create keys from an ordinary user account rather than an admin when the caller only needs to read alerts or ping heartbeats.

Requests carrying the header are treated as pure API calls: responses are JSON and there are no redirects to the sign-in page.

Expiry and revocation

An expired key is refused with 401 API key has expired. To stop a key early, choose Revoke in the list; the confirmation reads “Any systems using this key will immediately lose access. This action cannot be undone.” Revocation is immediate and permanent - create a new key rather than trying to restore one.

There is no in-place rotation. The pattern is: create the new key, deploy it, confirm the old key’s last-used activity has stopped, then revoke the old one.

The legacy key

Accounts created before named keys existed have a single per-user key shown under Legacy API Key. It keeps working, and it can be regenerated, but new integrations should use named keys so each system can be revoked on its own.

With akmcp

The open-source MCP server for self-managed installs reads the key from the ALERTKICK_API_KEY environment variable or an api_key field in its config file, and sends it as X-API-Key on every request:

{
  "mcpServers": {
    "alertkick": {
      "command": "/path/to/akmcp",
      "env": {
        "ALERTKICK_API_KEY": "ak.your_key_here",
        "ALERTKICK_API_URL": "https://your-team.alertkick.com"
      }
    }
  }
}

See Use AlertKick with your AI assistant for the rest of that setup and the MCP tool reference for what the key can then do.

Key hygiene

• One key per system, named after it, so a compromised or retired system can be revoked without touching the others.
• Set an expiry on keys held by people; leave No expiry for unattended systems you would rather not have fail at 3 AM on a Sunday.
• Keep keys out of shell history and CI logs; pass them through environment variables or a secrets store.
• Inbound integrations (Prometheus, Grafana, and the rest) use a per-integration service key, not a user API key. See Inbound alert sources.