API Tokens

API tokens allow you to authenticate with the Hoppla API for automation and integrations. Tokens are scoped to your team and can be restricted to specific permissions using fine-grained scopes.

Creating a Token

1. Go to Settings > API Tokens.
2. Click Create Token.
3. Give the token a descriptive name (e.g., "CI/CD Pipeline", "Monitoring Dashboard").
4. Select the scopes (permissions) the token needs.
5. Optionally set an expiration date.
6. Click Create.
7. Copy the token immediately.

WARNING

The token is only displayed once at creation time. If you lose it, you will need to create a new one.

What a token looks like

A Hoppla API token is an opaque key that starts with sk- and is around 55 characters long, for example:

sk-a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVwXyZ...

You see the full token once, right after you create it. Afterwards the token list shows only a masked stub like sk-...aB3d so you can tell your tokens apart -- the secret part is never shown again.

Token Scopes

Tokens use fine-grained scopes organized by resource domain. Each domain supports three access levels:

Level	Description
:read	Read-only access to the resource
:write	Create, update, and delete operations
:manage	Full access (grants both :read and :write)

Available Scope Domains

Domain	Read	Write	Covers
monitors	List monitors, stats, uptime, performance	Create, update, delete monitors	CRUD + all check type stats
checks	View results, timeseries, crawl runs	Update, enable, disable, snooze, trigger checks	Check lifecycle management
incidents	List and view incidents	Create, update, acknowledge, snooze, delete incidents	Incident lifecycle
notifications	List channels, rules, logs	Create/update channels and rules, send tests	Alerting configuration
escalation	View policies and on-call schedules	Create/update policies, schedules, rotations	On-call management
status-pages	View status pages and subscribers	Create/update pages, manage domains	Public status pages
maintenance	View maintenance windows	Create/update maintenance windows	Planned downtime
team	View members and invitations	Invite, update roles, remove members	Team management
settings	View branding, SMTP, SSO, audit log	Update branding, SMTP, SSO, reports	Account configuration
billing	View plans, transactions, invoices	Change plans, manage subscriptions	Billing management

Example: CI/CD Token

A deployment pipeline that only needs to manage monitors:

Scopes: monitors:manage, checks:write

Example: Read-Only Dashboard

An internal dashboard that displays monitoring data:

Scopes: monitors:read, incidents:read, checks:read

Example: Full Access

A management tool that needs complete API access:

Scopes: monitors:manage, checks:manage, incidents:manage, notifications:manage,
        escalation:manage, status-pages:manage, maintenance:manage, team:manage,
        settings:manage, billing:manage

Scope Escalation Prevention

When creating a new token using an existing API token, the new token's scopes must be a subset of the creating token's scopes. A token with monitors:read cannot create a token with monitors:write.

Legacy scopes

Older tokens may use the simpler read and read, write scopes instead of the granular resource:action scopes shown above. These are still accepted, so existing integrations keep working.

Plan Restrictions

On the Free plan (and on demo accounts), API tokens are limited to :read scopes only. To create tokens with write access, upgrade to the Hobby plan or higher.

Listing Available Scopes

Use the API to fetch all available scopes with descriptions:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.hoppla.dev/api/v1/api-tokens/scopes

Multi-Team Tokens

If your account (the same email address) belongs to more than one team, a single token can access several of them at once — handy for cross-team automation or AI assistants. By default a token can access every team you belong to; you explicitly exclude any it shouldn't reach. Your current team is always included. (If you only belong to one team, a token simply covers that team — nothing to configure.)

In the dashboard: when you belong to more than one team, the Create API Token dialog shows a Teams section with all your teams pre-selected. Uncheck any team you want to exclude.

Via the API:

• Omit tenant_ids → the token spans every team you can access (the default).
• Send a tenant_ids array to restrict it to exactly those teams (the not-excluded set):

curl -X POST https://app.hoppla.dev/api/v1/api-tokens \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Two teams only",
    "scopes": ["monitors:read", "incidents:read"],
    "tenant_ids": ["<team-id-a>", "<team-id-b>"]
  }'

• You can only reference teams your identity actually belongs to — unknown or unauthorized IDs are ignored, and your own team is always kept.
• To scope a token to your current team only, send "tenant_ids": [].
• When a token reaches several teams, list endpoints return data across all of them, tagged per team. The token list shows a token's team reach.

Team membership is checked live: if your access to a team is later removed, the token immediately stops reaching it.

Using a Token

Include the token in the Authorization header of your API requests:

Authorization: Bearer YOUR_TOKEN

Example with curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.hoppla.dev/api/v1/monitors

Example with JavaScript:

const response = await fetch('https://app.hoppla.dev/api/v1/monitors', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

Editing a Token

You can change an existing token's name, scopes, expiry, and team access at any time — the token value stays the same, so your integrations keep working.

In the dashboard: click the edit (pencil) icon on a token, adjust the fields, and choose Save Changes.

Via the API: send a PATCH with only the fields you want to change:

curl -X PATCH https://app.hoppla.dev/api/v1/api-tokens/<token-id> \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["monitors:read", "incidents:read"] }'

• Only the fields you include are changed; anything you omit is left as-is.
• The same limits apply as when creating a token: your plan, your role, and — if you edit via an API token — that token's own permissions. A token can never be edited to exceed them.
• Editing never changes the secret. To rotate the secret, delete the token and create a new one.

Revoking a Token

1. Go to Settings > API Tokens.
2. Find the token you want to revoke.
3. Click Delete.

Revocation takes effect immediately. Any requests using the deleted token will receive a 401 Unauthorized response.

Security Best Practices

• Use the minimum scopes necessary. Only grant the permissions your integration actually needs.
• Do not commit tokens to version control. Use environment variables or a secrets manager instead.
• Use separate tokens per integration. This way you can revoke access to a single integration without affecting others.
• Set expiration dates. Tokens can be set to expire after 30, 60, 90 days, or 1 year.
• Rotate tokens regularly. Create a new token, update your integrations, then delete the old one.
• Monitor API usage. If you suspect a token has been compromised, revoke it immediately and create a replacement.