API Reference

Request a proof-of-work challenge. Required before signup if hashcash is enabled.

Headers

Response

{
  "challenge": "base64-encoded-challenge",
  "difficulty": 5,
  "algorithm": "argon2id",
  "params": {
    "time_cost": 2,
    "memory_cost": 19456,
    "parallelism": 1,
    "hash_len": 32
  },
  "expires_in": 300
}

Register a new user. Sends a verification email (link or code, depending on app config).

Headers

Request body

Response

{
  "status": "verification_sent",
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sign in with password or request a magic link.

Headers

Request body

Response (password strategy)

{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBpcyBh...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-..."
}

Also sets the __session cookie with the access JWT.

Response (magic_link strategy)

{
  "status": "magic_link_sent",
  "user_id": null
}

Verify email address or consume a magic link sign-in token. Redirects the user after verification.

Query parameters

Response

HTTP 302 redirect to the redirect_url stored in the token, or the app's primary domain, or /. Sets the __session cookie.

Verify email or sign in using a 6-digit code sent by email.

Headers

Request body

Response

{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBpcyBh...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-..."
}

Get the authenticated user's info. Requires a valid session.

Authentication

Cookie __session or Authorization: Bearer <jwt>

Response

{
  "user_id": "550e8400-...",
  "email": "[email protected]",
  "email_verified": true
}

Revoke the current session and clear the session cookie.

Authentication

Cookie __session or Authorization: Bearer <jwt>

Response

{
  "status": "logged_out"
}

Exchange a refresh token for a new access token. The refresh token is rotated on each use.

Headers

Request body

Response

{
  "access_token": "eyJhbGci...",
  "refresh_token": "new-rotated-token...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-..."
}

Generate a one-time SSO token for cross-domain authentication. Redirects the user to the target URL with the token appended as a query parameter.

Authentication

Cookie __session or Authorization: Bearer <jwt>

Query parameters

Response

HTTP 302 redirect to {return_to}?__sso_token={token}. Token expires after 60 seconds.

Exchange a one-time SSO token for a session. The source and target apps must belong to the same tenant.

Headers

Request body

Response

{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBpcyBh...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-..."
}

Register a bot using a confirmed confirmations.info donation challenge and an Ed25519 public key. Each challenge can only be used once.

Headers

Request body

Response

{
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_key": "base64-encoded-ed25519-public-key"
}

Authenticate a bot by verifying an Ed25519 signature. Returns a standard session with JWT and refresh token.

Headers

Request body

Signature

Sign the following message with the bot's Ed25519 private key:

ezauth:bot_auth:{app_id}:{bot_id}:{timestamp}

The timestamp must be within 5 minutes of server time.

Response

{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBpcyBh...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-..."
}

List all users for an application. Supports pagination and email filtering.

Authentication

Authorization: Bearer sk_...

Query parameters

Response

{
  "users": [
    {
      "id": "550e8400-...",
      "email": "[email protected]",
      "email_verified": true,
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T09:30:00Z"
    }
  ],
  "total": 42
}

Create a user server-side. Skips verification and rate limits.

Authentication

Authorization: Bearer sk_...

Request body

Response 201

{
  "id": "550e8400-...",
  "email": "[email protected]",
  "email_verified": false,
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

Retrieve a specific user by ID.

Authentication

Authorization: Bearer sk_...

Response

{
  "id": "550e8400-...",
  "email": "[email protected]",
  "email_verified": true,
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

Revoke a session by ID. The user's JWT will be invalid on next verification.

Authentication

Authorization: Bearer sk_...

Query parameters

Response

{
  "status": "revoked"
}

Create a short-lived session for a user server-side. Useful for impersonation or server-initiated sign-in flows.

Authentication

Authorization: Bearer sk_...

Request body

Response

{
  "token": "eyJhbGci...",
  "refresh_token": "dGhpcyBpcyBh...",
  "user_id": "550e8400-...",
  "session_id": "660e8400-...",
  "expires_at": "2025-01-15T09:35:00Z"
}

Retrieve the JSON Web Key Set for verifying JWTs. No authentication required.

App resolution

Pass ?app_id=... as a query parameter, or the app is resolved from the Host header via a verified domain.

Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "app-uuid",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-modulus...",
      "e": "AQAB"
    }
  ]
}