Skip to main content

Authentication

JWT Bearer tokens​

Register​

POST /auth/register

Creates a new tenant with an admin user.

curl -X POST https://api.haltless.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "SecureP@ss123!",
    "full_name": "Jane Smith",
    "tenant_name": "Acme Manufacturing"
  }'

Request body:

FieldTypeRequiredConstraints
emailstringYesValid email
passwordstringYesMin 8 chars, complexity required
full_namestringYes
tenant_namestringYes

Response 201:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "mfa_required": false
}

Login​

POST /auth/login

curl -X POST https://api.haltless.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "SecureP@ss123!"}'

Response 200:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "mfa_required": false
}

If MFA is enabled, mfa_required will be true and the access_token is a short-lived pending token. Complete login via POST /auth/mfa/verify.

Refresh token​

POST /auth/refresh

Exchange the refresh_token cookie for a new token pair.

curl -X POST https://api.haltless.io/api/v1/auth/refresh \
  --cookie "refresh_token=..."

Get current user​

GET /auth/me

curl https://api.haltless.io/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "id": "uuid",
  "email": "admin@example.com",
  "full_name": "Jane Smith",
  "tenant_id": "uuid",
  "role": "admin",
  "is_active": true,
  "mfa_enabled": false,
  "onboarding_completed": true,
  "subscription_status": "active",
  "subscription_tier": "pro"
}

Logout​

POST /auth/logout

Blocklists the current access and refresh tokens.

curl -X POST https://api.haltless.io/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

MFA endpoints​

Setup MFA​

POST /auth/mfa/setup

Returns a TOTP secret and QR code URI.

Confirm MFA setup​

POST /auth/mfa/verify-setup

Body: {"code": "123456"}

Verify MFA on login​

POST /auth/mfa/verify

Body: {"mfa_token": "pending_token", "code": "123456"}

Disable MFA​

POST /auth/mfa/disable

Body: {"code": "123456"}

API key authentication​

See API Keys Guide for detailed usage.

Endpoints that accept API key auth:

EndpointDescription
POST /ingestBatch sensor data ingestion
GET /agent/heartbeatEdge agent health check

SSO (Enterprise)​

Check SSO availability​

GET /auth/sso/check?email=user@company.com

Exchange SSO code​

POST /auth/sso/exchange

Body: {"code": "sso_code_from_callback"}

Configure SSO (admin)​

POST /auth/sso/config

{
  "provider_name": "Okta",
  "client_id": "0oabc...",
  "client_secret": "secret",
  "discovery_url": "https://org.okta.com/.well-known/openid-configuration",
  "domain": "company.com"
}

GET /auth/sso/config | PATCH /auth/sso/config | DELETE /auth/sso/config