Getting Started

This guide walks you through your first integration with the Hoppla reseller API.

Prerequisites

• A signed reseller contract (12-month minimum term, paid monthly or yearly) — see Pricing & Contract Terms
• A Hoppla account with the reseller role (activated after contract signing)
• Your login credentials (email + password)

Authentication

All API requests require a Bearer token. Obtain one by exchanging your credentials:

curl -X POST https://app.hoppla.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "device_name": "Integration Server"
  }'

Response (201):

{
  "token": "ss-aB3dLookup9xKsecretValue1234...",
  "user": {
    "id": "9a1b2c3d-...",
    "name": "Reseller Account",
    "email": "[email protected]",
    "tenant_id": "tenant-uuid-...",
    "role": "admin",
    "language": "en",
    "managed_teams": []
  }
}

The token is shown only once — store it securely. Use the token value in all subsequent requests:

Authorization: Bearer ss-aB3dLookup9xKsecretValue1234...

For server-to-server automation we recommend a dedicated reseller management token (rk-…) instead of a session token — see API Reference — Reseller API Tokens. Reseller management endpoints require a reseller-scoped token; a general read token does not work on them.

Quick Start: API

1. Create a Managed Team

Provision a new team (tenant) for your customer:

curl -X POST https://app.hoppla.dev/api/v1/reseller/managed-teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "starter",
    "label": "Enterprise Client #42",
    "admin_email": "[email protected]",
    "admin_name": "Jane Doe",
    "admin_password": "securepassword123"
  }'

Response (201):

{
  "data": {
    "id": "mt-uuid-...",
    "tenant_id": "new-tenant-uuid-...",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "starter",
    "label": "Enterprise Client #42",
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-01-15T10:30:00.000000Z"
  }
}

2. List Your Managed Teams

curl https://app.hoppla.dev/api/v1/reseller/managed-teams \
  -H "Authorization: Bearer $TOKEN"

3. Impersonate a Team

Access a managed team's resources by setting the X-Tenant-Id header:

curl https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: new-tenant-uuid-..."

This returns monitors belonging to the managed team, not your own tenant.

4. Create a Monitor in a Managed Team

curl -X POST https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: new-tenant-uuid-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Website",
    "url": "https://acmecorp.com",
    "type": "uptime",
    "interval": 60,
    "is_enabled": true
  }'

5. View Team Summary

curl https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../summary \
  -H "Authorization: Bearer $TOKEN"

Returns monitor counts, incident counts, and health overview for the team.

6. View Team Usage

curl https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../usage \
  -H "Authorization: Bearer $TOKEN"

Returns usage metrics for billing purposes.

Quick Start: Dashboard

1. Log in at https://app.hoppla.dev with your reseller credentials
2. Navigate to Teams in the sidebar
3. Click Create Team to provision a new customer
4. Fill in team name, slug, plan, and optional admin user
5. Click View as this team to manage their monitors and settings
6. Use the team selector dropdown to switch back to your own context

White-Label Branding

Customize how your managed teams' users see notifications and emails:

1. Set branding — PATCH /branding with your brand name, alert prefix, logos, colors, and footer
2. Configure SMTP (optional) — PATCH /smtp-config to send emails from your own domain
3. All notification channels (email, Slack, Discord, Teams, Telegram, PagerDuty, webhook) will use your custom branding

See API Reference — Branding and API Reference — Custom SMTP for details.

Next Steps

• API Reference — Full endpoint documentation (teams, branding, SMTP, channels)
• Impersonation — How cross-tenant access works
• Webhooks — Subscribe to provisioning and monitor events