Authentication

Purpose

Show how to authenticate to the Get2Dial API as a user, and describe the separate scheme edge nodes use.

Overview

User requests carry a stateless HS256 JWT as a Bearer token. The token is obtained from POST /api/v1/auth/login and validated on every /api/v1 request; its claims (tid, sub, email, role) pin the request to a tenant and role. Edge nodes use a different scheme — a node API key — on the /api/v1/nodes/* endpoints.

Logging in

POST /api/v1/auth/login accepts:

{
  "email": "agent@example.com",
  "password": "••••••••",
  "tenant_domain": "acme.get2dial.com"
}

tenant_domain is optional. When omitted, the workspace is resolved from the email (the password disambiguates if the email exists in more than one tenant), falling back to the platform default domain.

On success you get a token, its expiry, and the user object:

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs…",
    "expires_at": "2026-07-01T12:00:00Z",
    "user": {
      "id": "…",
      "tenant_id": "…",
      "email": "agent@example.com",
      "role": "agent",
      "status": "active",
      "must_change_password": false,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  }
}

Using the token

Send it as a bearer token on every subsequent request:

curl -s https://api.get2dial.com/api/v1/auth/me \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs…'

WebSocket endpoints (/ws/supervisor, /ws/agent) can’t set headers on the upgrade, so they take the token as a ?token=<jwt> query parameter instead.

Examples

# Log in and capture the token (jq)
TOKEN=$(curl -s https://api.get2dial.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@acme.get2dial.com","password":"••••••••"}' \
  | jq -r .data.token)

# Change your own password
curl -s -X POST https://api.get2dial.com/api/v1/auth/me/password \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"current_password":"••••","new_password":"••••••••••••"}'

Notes

Tokens are stateless — POST /api/v1/auth/logout is audit-only; there is no server-side revocation yet. The default lifetime is 12h (AUTH_JWT_TTL_SECONDS).
Failed logins lock an account after 10 attempts for 15 minutes, and all failures return a generic invalid credentials so emails/workspaces can’t be enumerated.
A platform_admin (in the reserved Platform tenant) may act cross-tenant via ?tenant_id=; every other role is confined to its own tenant.
Node auth is separate: the edge node agent presents a raw API key (issued at registration) as a bearer token, matched against the SHA-256 digest stored in nodes.api_key_hash. Node endpoints force tenant/node identity from that key.