API Reference

HelloJohn exposes a REST API over HTTPS. All requests and responses use JSON.

Base URLs

The v1 prefix is included in every endpoint path shown in this reference.

Authentication

Every request (except public auth endpoints) requires a bearer token in the Authorization header.

Authorization: Bearer <token>

There are three token types accepted depending on the endpoint:

Obtain a secret key from your HelloJohn dashboard → Settings → API Keys.

Tenant scoping

Data Plane endpoints (users, sessions, MFA, organizations) are scoped to a specific tenant via the X-Tenant-ID header:

curl https://api.hellojohn.dev/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Control Plane endpoints (/cp/ prefix) do not require X-Tenant-ID.

Versioning

The current API version is v1. Breaking changes will be released as v2, with a 6-month deprecation window. Non-breaking additions (new fields, new endpoints) are added without a version bump.

Check the X-HelloJohn-Version response header to see the exact server version:

X-HelloJohn-Version: 1.4.2

Pagination

List endpoints return paginated results using cursor-based pagination.

Request parameters:

Response shape:

{
  "data": [...],
  "pagination": {
    "total": 1482,
    "limit": 20,
    "has_more": true,
    "next_cursor": "cur_01HABCDEF123456"
  }
}

Pass next_cursor as the cursor parameter in the next request to fetch the following page.

Filtering & Sorting

Most list endpoints accept query parameters for filtering:

GET /v1/users?email=alice@example.com&status=active&sort=created_at&order=desc

Common parameters across all list endpoints:

Request Format

Send JSON in the request body with Content-Type: application/json:

curl -X POST https://api.hellojohn.dev/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -d '{"email": "user@example.com", "password": "s3cur3P@ss"}'

Response Format

All responses return JSON. Successful responses use 2xx status codes.

{
  "id": "usr_01HABCDEF123456",
  "email": "user@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

Errors use 4xx / 5xx codes with a structured error body:

{
  "error": {
    "code": "user_not_found",
    "message": "No user found with the provided ID.",
    "status": 404,
    "request_id": "req_01HABCDEF999888"
  }
}

See Error Codes for the complete list.

Rate Limits

All endpoints are rate-limited. Limits vary by endpoint sensitivity.

Rate limit status is returned in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1700000060

When a limit is exceeded, HelloJohn returns 429 Too Many Requests. See Rate Limits.

Idempotency

POST requests to mutating endpoints support idempotency keys to prevent duplicate operations (e.g., accidental retries):

curl -X POST https://api.hellojohn.dev/v1/users \
  -H "Idempotency-Key: my-unique-key-abc123" \
  ...

The same request with the same Idempotency-Key within 24 hours returns the cached response without creating a duplicate.

OpenAPI Spec

A machine-readable OpenAPI 3.0 spec is available at:

https://api.hellojohn.dev/openapi.json

Import it into Postman, Insomnia, or any OpenAPI-compatible tool.

SDKs

Instead of calling the REST API directly, use an official SDK:

• Node.js / TypeScript
• Go
• Python
• React
• Next.js