Authentication

The Hoody Authentication API covers account signup, sign-in (email/password, GitHub, Google, device flow), JWT-based session management, identity claims for third-party verification, and two-factor authentication (2FA). Use these endpoints to register new accounts, exchange credentials for access and refresh tokens, manage the current session, and protect accounts with TOTP-based 2FA.

All authenticated endpoints accept Authorization: Bearer <jwt>. After 2FA is enabled on an account, sensitive token-mutation endpoints additionally require a TOTP code.

`GET /api/v1/auth/available-regions`

Returns regions where free-tier servers exist, with boolean availability. Public, no auth required.

This endpoint takes no parameters.

curl -X GET https://api.hoody.icu/api/v1/auth/available-regions

await client.api.authentication.getAvailableRegions();

{
  "statusCode": 200,
  "data": {
    "regions": [
      {
        "region": "eu-west",
        "country": "France",
        "city": "Paris",
        "available": true
      },
      {
        "region": "us-east",
        "country": "United States",
        "city": "Ashburn",
        "available": true
      },
      {
        "region": "ap-southeast",
        "country": "Singapore",
        "city": "Singapore",
        "available": false
      }
    ]
  }
}

`GET /api/v1/auth/config`

Returns the public sign-in configuration (such as which identity providers are enabled) used to drive the OAuth flow.

This endpoint takes no parameters.

curl -X GET https://api.hoody.icu/api/v1/auth/config

await client.api.authentication.getOAuthConfig();

{
  "statusCode": 200,
  "message": "Public sign-in configuration"
}

`GET /api/v1/meta/public-key`

Returns the ED25519 public key(s) used by Hoody to sign all API responses (X-Hoody-Signature header), identity claims issued at login, and container authorization claims.

This endpoint is intentionally public and requires no authentication.

This endpoint takes no parameters.

Signing formats

The data.signing_format object documents the wire formats used by Hoody’s signed artifacts. The fields you need most often are:

response_header: X-Hoody-Signature: t=<unix_ts>,kid=<key_id>,m=<method>,s=<status>,path=<request_url>,sig=<hex>
response_signed_data: ${t}\n${method}\n${status}\n${path}\n${responseBody} — the newline-joined tuple of timestamp, HTTP method, response status, request path, and response body. The body is the UTF-8 string of the JSON payload.
identity_claim_signed_data: base64url(JSON.stringify(claim_payload)) — the b64url string itself (UTF-8 bytes).
container_claim_signed_data: same as identity_claim_signed_data.
replay_tolerance_seconds: recommended maximum age (|now - t|) for response-signature freshness checks.

Verification flow

Fetch this endpoint once (cache for 24h+).
Locate the key by kid from the keys[] array.
For response signatures: parse the X-Hoody-Signature header and verify sig against the newline-joined tuple ${t}\n${method}\n${status}\n${path}\n${responseBody}.
For identity/container claims: verify claim.signature_hex against the UTF-8 bytes of claim.payload_b64.
If kid in a signature/claim does not match any cached key, re-fetch this endpoint.

curl -X GET https://api.hoody.icu/api/v1/meta/public-key

await client.api.meta.getPublicKey();

{
  "statusCode": 200,
  "message": "Hoody API signing public key",
  "data": {
    "keys": [
      {
        "kid": "v1",
        "algorithm": "ed25519",
        "public_key_hex": "8c8d683c125761bd9157e3a6f98c30d81cd7f2be4d16062a8342d1fcd2ca474a",
        "public_key_b64": "jI1oPBJXYb2RV+Om+YwwwlzX8r5NFgYqg0LRzSykd0o=",
        "public_key_b64url": "jI1oPBJXYb2RV-Om-YwwwlzX8r5NFgYqg0LRzSykd0o"
      }
    ],
    "active_kid": "v1",
    "usage": ["response-signing", "identity-claims", "container-claims"],
    "signing_format": {
      "response_header": "X-Hoody-Signature: t=<unix_ts>,kid=<key_id>,m=<method>,s=<status>,path=<request_url>,sig=<hex>",
      "response_signed_data": "<t>\\n<method>\\n<status>\\n<path>\\n<response_body_utf8_string>",
      "identity_claim_signed_data": "base64url(JSON.stringify(claim_payload)) — the b64url string itself (UTF-8 bytes)",
      "container_claim_signed_data": "base64url(JSON.stringify(container_claim_payload)) — the b64url string itself (UTF-8 bytes)",
      "replay_tolerance_seconds": 300
    }
  }
}

{
  "statusCode": 503,
  "error": "SIGNING_NOT_CONFIGURED",
  "message": "Response signing is not configured on this API instance"
}

Identity claims

An identity claim is a short-lived, ED25519-signed credential Hoody returns to a freshly authenticated user. It proves “Hoody authenticated this user” to systems outside Hoody — container programs, third-party services, downstream APIs — and is verified offline against the public key fetched from GET /api/v1/meta/public-key.

The claim is returned (when signing is configured on the server) by:

Password login — POST /api/v1/users/auth/login (see below)
2FA completion — POST /api/v1/users/auth/2fa/verify (see below)
Email verification in tokens mode — POST /api/v1/auth/verify-email (see below)
Device flow terminal — POST /api/v1/auth/device/token
Hosted-auth exchange — POST /api/v1/auth/exchange

It is omitted when response_mode=intent is requested (the hosted-auth UI flow defers issuance to the PKCE exchange) and when HOODY_SIGNING_PRIVATE_KEY is not configured on the server instance.

Bundle format

Field	Type	Description
`kid`	string	Key identifier. Look up the matching key in `keys[]` from `GET /api/v1/meta/public-key`.
`payload_b64`	string	base64url-encoded JSON payload (the string itself is the signed input).
`signature_hex`	string	ED25519 detached signature over UTF-8 bytes of `payload_b64` (128 hex chars = 64 bytes).

Payload fields

Field	Type	Description
`claim_type`	string	Always `"identity"` for claims returned by Hoody auth flows.
`iss`	string	Always `"hoody-api"`.
`sub`	string	The authenticated user’s id.
`username`	string	The authenticated account’s username.
`type`	string	`"user"` or `"admin"`.
`iat`	number	Unix timestamp (seconds) when the claim was issued.
`exp`	number	Unix timestamp (seconds) when the claim expires. Default lifetime is approximately 30 days for login-time claims.
`kid`	string	The signing key id used to issue this claim.
`aud`	string	Audience binding (only present on audience-bound re-issued claims). See strict two-way semantics in the verification checklist below.

Verification (mandatory checks)

Reject the claim if any of the following fail:

Signature verifies against the UTF-8 bytes of payload_b64 (not the decoded JSON), using the public key whose kid matches payload.kid and bundle.kid.
payload.claim_type === "identity".
payload.iss === "hoody-api".
payload.exp > now and payload.exp > payload.iat.
payload.iat <= now + 300 (300-second clock skew tolerance).
payload.kid === bundle.kid.
If your flow uses audience binding, both directions must hold: the verifier’s audience matches payload.aud, and payload.aud matches the verifier’s identifier (strict two-way audience semantics).

import { createPublicKey, verify, createHash } from 'node:crypto';

const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');

function buildSpki(raw32) {
  return Buffer.concat([SPKI_PREFIX, raw32]);
}

const kid = 'v1';
const hex  = '8c8d683c125761bd9157e3a6f98c30d81cd7f2be4d16062a8342d1fcd2ca474a';
const rawKey = Buffer.from(hex, 'hex');
const pubKey = createPublicKey({ key: buildSpki(rawKey), format: 'der', type: 'spki' });

const claim = /* ...identity_claim from response... */;
const payloadBytes = Buffer.from(claim.payload_b64, 'utf8');
const sigBytes     = Buffer.from(claim.signature_hex, 'hex');

if (!verify(null, payloadBytes, pubKey, sigBytes)) {
  throw new Error('Identity claim signature invalid');
}

import nacl from 'tweetnacl';

const hex     = '8c8d683c125761bd9157e3a6f98c30d81cd7f2be4d16062a8342d1fcd2ca474a';
const pubKey  = Buffer.from(hex, 'hex');

const ok = nacl.sign.detached.verify(
  Buffer.from(claim.payload_b64, 'utf8'),
  Buffer.from(claim.signature_hex, 'hex'),
  pubKey,
);
if (!ok) throw new Error('Identity claim signature invalid');

Decodable example claim

{
  "kid": "v1",
  "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0Mzg4MjAwMCwia2lkIjoidjEifQ",
  "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
}

Decoded payload_b64 (base64url) gives:

{
  "sub": "a1b2c3d4e5f6789012345678",
  "username": "alice",
  "type": "user",
  "iat": 1741290000,
  "exp": 1743882000,
  "kid": "v1"
}

Gating access in proxied apps

There are three patterns for letting a proxied app (one running inside a Hoody container, routed through the Hoody proxy) decide whether the inbound request carries a valid Hoody identity. Try them in this order:

Native hoody-identity permission group. The built-in proxy permission group that exposes the parsed identity claim to proxied apps. See the hoody-identity permission group.
App-level header. Read a non-reserved request header that the upstream caller (your gateway or the Hoody dashboard) sets to the claim bundle. The convention used by Hoody and downstream consumers is X-Hoody-Claim: <payload_b64>.<signature_hex> with a pinned kid.

The X-Hoody-Identity-* header namespace is reserved by the Hoody edge and is unconditionally stripped before any request reaches your app. A claim sent under any X-Hoody-Identity-* header never arrives — forward the claim bundle under a non-reserved header such as X-Hoody-Claim instead.
Proxy hook. A request-time hook in your app’s hoody.json that receives the headers (and claim bundle, if forwarded) and decides whether to allow the request. See the identity-claim-auth-gate hook recipe, which likewise reads from the non-reserved x-hoody-claim header.

For container-side, per-process claims (claims that prove a Hoody user authorized a specific command inside a single container, not the cross-app identity claim described here), see Identity claims on the Containers API.

OAuth flows

`GET /api/v1/auth/device/authorize`

GET endpoint the verification page navigates to. Verifies the provider is fully configured (302 back to the device page with ?error=provider_unavailable, ticket intact, when not), then consumes the device_verify_ticket + __Host-device_verify cookie atomically and redirects to the provider with a server-injected device_binding + attempt nonce. Sets Referrer-Policy: no-referrer.

Parameters

Name	In	Type	Required	Description
`ticket`	query	string	Yes	—
`provider`	query	string	Yes	One of: `github`, `google`.

curl -X GET "https://api.hoody.icu/api/v1/auth/device/authorize?ticket=5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c&provider=github"

await client.api.authentication.oauthDeviceAuthorize({ ticket: '5b8e...', provider: 'github' });

{}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Ticket invalid or provider unavailable"
}

{
  "statusCode": 410,
  "error": "Gone",
  "message": "Device verification ticket has expired or been consumed"
}

`GET /api/v1/auth/github`

Redirects the browser to GitHub for OAuth authentication. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`intent`	query	string	No	OAuth intent: `login` (default). `star_check` is accepted but ignored (retired).
`redirect_uri`	query	string	Yes	Frontend URL to redirect to after OAuth completes (must be on an allowed domain).
`code_challenge`	query	string	Yes	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`). Required — all OAuth flows must use PKCE post-migration.
`invite_code`	query	string	No	Optional invite code (“coupon”) captured from the signup link. Normalized and hashed at redirect time — only the hash travels in the OAuth state, never the raw code. Memorized hash-only on a NEW account and applied automatically; not validated here.

curl -X GET "https://api.hoody.icu/api/v1/auth/github?intent=login&redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

await client.api.authentication.githubOAuthRedirect({
  redirect_uri: 'https://app.example.com/auth/callback',
  code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
});

{}

`GET /api/v1/auth/github/callback`

Handles the GitHub OAuth callback. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`code`	query	string	No
`state`	query	string	Yes
`error`	query	string	No	Provider-side failure code (e.g. `access_denied`). Present instead of `code` when the user declines.
`error_description`	query	string	No
`error_uri`	query	string	No

curl -X GET "https://api.hoody.icu/api/v1/auth/github/callback?code=ac123&state=550e8400-e29b-41d4-a716-446655440000"

await client.api.authentication.githubOAuthCallback({ code: 'ac123', state: '550e...ce0' });

{}

`GET /api/v1/auth/google`

Redirects the browser to Google for OAuth authentication. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`redirect_uri`	query	string	Yes	Frontend URL to redirect to after OAuth completes (must be on an allowed domain).
`code_challenge`	query	string	Yes	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`). Required — all OAuth flows must use PKCE post-migration.
`invite_code`	query	string	No	Optional invite code (“coupon”) captured from the signup link. Normalized and hashed at redirect time — only the hash travels in the OAuth state, never the raw code. Memorized hash-only on a NEW account and applied automatically; not validated here.

curl -X GET "https://api.hoody.icu/api/v1/auth/google?redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

await client.api.authentication.googleOAuthRedirect({
  redirect_uri: 'https://app.example.com/auth/callback',
  code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
});

{}

`GET /api/v1/auth/google/callback`

Handles the Google OAuth callback. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`code`	query	string	No
`state`	query	string	Yes
`error`	query	string	No	Provider-side failure code (e.g. `access_denied`). Present instead of `code` when the user declines.
`error_description`	query	string	No
`error_uri`	query	string	No

curl -X GET "https://api.hoody.icu/api/v1/auth/google/callback?code=ac123&state=550e8400-e29b-41d4-a716-446655440000"

await client.api.authentication.googleOAuthCallback({ code: 'ac123', state: '550e...ce0' });

{}

`GET /api/v1/auth/launch/start`

GET endpoint the popup navigates to. Consumes the launch ticket atomically and runs the existing OAuth redirect flow. Sets Referrer-Policy: no-referrer.

Parameters

Name	In	Type	Required	Description
`ticket`	query	string	Yes	One-shot ticket from `/launch/initiate` response.

curl -X GET "https://api.hoody.icu/api/v1/auth/launch/start?ticket=5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c"

await client.api.authentication.oauthLaunchStart({ ticket: '5b8e...9b0c' });

{}

{
  "statusCode": 410,
  "error": "Gone",
  "message": "Launch ticket has expired or been consumed"
}

`POST /api/v1/auth/authorize`

Registers a PKCE authorization request (code challenge + redirect URI) to begin the browser sign-in flow.

Request Body

Name	Type	Required	Description
`code_challenge`	string	Yes	PKCE challenge, 43 chars.
`redirect_uri`	string	Yes	Must start with `https://`.

curl -X POST https://api.hoody.icu/api/v1/auth/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

await client.api.authentication.oauthAuthorize({
  code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
  redirect_uri: 'https://app.example.com/auth/callback',
});

{
  "statusCode": 200,
  "message": "Authorization request registered"
}

`POST /api/v1/auth/device/code`

Issues a device_code (polled by the CLI) and a short, hand-typeable user_code (shown to the human). Public, no auth. RFC-8628-inspired but deliberately not a standards-compliant device grant: no client_id/grant_type, lifecycle errors are nested under data, and the poll interval is a fixed 5s after slow_down.

Request Body

Name	Type	Required	Description
`client_name`	string	No	Shown on the verification page as “X is requesting access”.
`code_challenge`	string	No	Optional PKCE on the device flow itself; if present the poll REQUIRES the verifier.

curl -X POST https://api.hoody.icu/api/v1/auth/device/code \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "Hoody CLI" }'

await client.api.authentication.oauthDeviceCode({ client_name: 'Hoody CLI' });

{
  "statusCode": 200,
  "data": {
    "device_code": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "user_code": "PQRS-ABCD",
    "verification_uri": "https://app.hoody.icu/device",
    "verification_uri_complete": "https://app.hoody.icu/device?code=PQRS-ABCD",
    "interval": 5,
    "expires_in": 600
  }
}

`POST /api/v1/auth/device/deny`

Page-only helper of the RFC-8628-inspired device flow (mirrors the RFC recommendation that the user can deny). Cookie + ticket gated, no credentials required — possession of the live ticket + cookie is the refusing authority. Flips the pending row to denied; the terminal poll then reports access_denied. status=pending-conditional: an approved row can never be un-approved.

Request Body

Name	Type	Required	Description
`ticket`	string	Yes	`device_verify_ticket` from `/device/verify_code`.

curl -X POST https://api.hoody.icu/api/v1/auth/device/deny \
  -H "Content-Type: application/json" \
  -d '{ "ticket": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }'

await client.api.authentication.oauthDeviceDeny({
  ticket: '5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c',
});

{
  "statusCode": 200,
  "data": {
    "status": "denied"
  }
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Device ticket cookie missing or invalid"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Device flow is disabled on this instance"
}

{
  "statusCode": 410,
  "error": "Gone",
  "message": "Device verification ticket has expired or been consumed"
}

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /ticket must match pattern \"^[0-9a-f]{64}$\""
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Request validation failed	The request body failed schema validation (e.g. a malformed ticket; for `/device/login` also a missing identifier or out-of-bounds field lengths).	Correct the request fields and retry.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	You have exceeded the rate limit for this endpoint.	Wait before making additional requests, or upgrade your plan for higher limits.

`POST /api/v1/auth/device/login`

Page-only helper. Verifies email/username + password with FULL login parity (shared per-account throttle, timing-normalized bcrypt) behind the device_verify_ticket + __Host-device_verify cookie gate. NEVER returns session tokens: no-2FA returns {status:"approved"} (tokens mint only at /device/token); 2FA returns {requires_2fa, temp_token} (device-bound partial, no code_challenge). Credential failures do NOT consume the ticket. Feature-flag off returns 404; schema-invalid body returns 422.

Request Body

Name	Type	Required	Description
`ticket`	string	Yes	`device_verify_ticket` from `/device/verify_code`.
`username`	string	No	Username (alternative to `email`).
`email`	string	No	Email address (alternative to `username`).
`password`	string	Yes	Account password (8-128 chars).

curl -X POST https://api.hoody.icu/api/v1/auth/device/login \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "username": "john_doe",
    "password": "SecurePassword123!"
  }'

await client.api.authentication.oauthDeviceLogin({
  ticket: '5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c',
  username: 'john_doe',
  password: 'SecurePassword123!',
});

{
  "statusCode": 200,
  "data": {
    "status": "approved",
    "requires_2fa": false
  }
}

{
  "statusCode": 401,
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password"
}

Error Code	Title	Description	Resolution
`INVALID_CREDENTIALS`	Invalid credentials	The provided username/email or password is incorrect.	Verify your credentials and try again, or use the password reset feature.
`EMAIL_NOT_VERIFIED`	Email not verified	Returned when the password is correct but the account’s email address has not been verified yet. Reachable only after bcrypt confirms the password, so it is not an enumeration oracle. Response carries `data.email` so the client can offer a ‘resend verification email’ CTA without re-prompting.	Complete email verification by clicking the link sent to your inbox, or call `/auth/resend-verification` to receive a new link, or complete a password reset which also implicitly verifies the email.

{
  "statusCode": 403,
  "error": "ACCOUNT_BANNED",
  "message": "Your account is banned"
}

Error Code	Title	Description	Resolution
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Device flow is disabled on this instance"
}

{
  "statusCode": 410,
  "error": "Gone",
  "message": "Ticket invalid/consumed/superseded, cookie mismatch, or row expired/denied — re-enter the user code"
}

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /ticket must match pattern \"^[0-9a-f]{64}$\""
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Request validation failed	The request body failed schema validation (e.g. a malformed ticket; for `/device/login` also a missing identifier or out-of-bounds field lengths).	Correct the request fields and retry.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	You have exceeded the rate limit for this endpoint.	Wait before making additional requests, or upgrade your plan for higher limits.

`POST /api/v1/auth/device/token`

Polled by the CLI while the user completes the browser step. Returns 400 + {data:{error}} for lifecycle states (authorization_pending | slow_down | access_denied | expired_token), 200 + token-set on approval (single-use; also requires the approving user’s session generation to still be current — a password reset / logout-all after approval yields expired_token), 429 on the outer flood guard. Public, no auth. Lifecycle errors are nested under data, unlike RFC 8628 §3.5.

Request Body

Name	Type	Required	Description
`device_code`	string	Yes	64 hex chars.
`code_verifier`	string	No	PKCE verifier, required when device flow was started with a challenge.

curl -X POST https://api.hoody.icu/api/v1/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }'

await client.api.authentication.oauthDeviceToken({ device_code: '5b8e...9b0c' });

{
  "statusCode": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-11-28T20:19:00.000Z",
    "expires_in": 86400,
    "refresh_expires_at": "2025-12-04T20:19:00.000Z",
    "refresh_expires_in": 604800,
    "identity_claim": {
      "kid": "v1",
      "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0Mzg4MjAwMCwia2lkIjoidjEifQ",
      "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
    },
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "john_doe",
      "alias": "John Doe",
      "email": "john.doe@example.com",
      "is_admin": false,
      "email_verified": true,
      "signup_method": "github",
      "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
      "created_at": "2024-12-01T10:00:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "server": {
      "id": "srv_abc123",
      "name": "eu-west-1a",
      "country": "France",
      "region": "eu-west",
      "city": "Paris",
      "datacenter": "PAR1",
      "is_ready": true
    },
    "project": {
      "id": "507f1f77bcf86cd799439022",
      "alias": "default"
    },
    "container": {
      "id": "507f1f77bcf86cd799439033",
      "name": "workspace-1",
      "status": "running"
    }
  }
}

{
  "statusCode": 400,
  "data": { "error": "authorization_pending" }
}

`POST /api/v1/auth/device/verify_code`

Page-only helper. On a live pending row, mints a one-time device_verify_ticket and sets the __Host-device_verify cookie. Leaks only client_name + coarse status.

Request Body

Name	Type	Required	Description
`user_code`	string	Yes	`XXXX-XXXX` user code (dashes optional).

curl -X POST https://api.hoody.icu/api/v1/auth/device/verify_code \
  -H "Content-Type: application/json" \
  -d '{ "user_code": "PQRS-ABCD" }'

await client.api.authentication.oauthDeviceVerifyCode({ user_code: 'PQRS-ABCD' });

{
  "statusCode": 200,
  "data": {
    "client_name": "Hoody CLI",
    "status": "pending"
  }
}

`POST /api/v1/auth/exchange`

Completes the PKCE authorization-code flow by exchanging an authorization code and its code verifier for authentication tokens.

Request Body

Name	Type	Required	Description
`code`	string	Yes	64 hex chars authorization code.
`code_verifier`	string	Yes	PKCE verifier (43-128 chars).
`redirect_uri`	string	Yes	Must start with `https://`.

curl -X POST https://api.hoody.icu/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "code_verifier": "qPsM3wSb1UvK8r2u4aD7nQ9Xz5tL3oF6iE0bN8sR2hP4yK1vW7cZ5jT9xA2dG",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

await client.api.authentication.oauthExchange({
  code: '5b8e...9b0c',
  code_verifier: 'qPsM3wSb1Uv...G',
  redirect_uri: 'https://app.example.com/auth/callback',
});

{
  "statusCode": 200,
  "message": "Authentication tokens issued"
}

`POST /api/v1/auth/forgot-password`

Send a password reset email. Always returns success to prevent email enumeration.

Request Body

Name	Type	Required	Description
`email`	string	Yes	Email address associated with the account.

curl -X POST https://api.hoody.icu/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "john.doe@example.com" }'

await client.api.authentication.forgotPassword({ email: 'john.doe@example.com' });

{
  "statusCode": 200,
  "message": "If an account matches that email, a reset link has been sent"
}

`POST /api/v1/auth/intent/cancel`

POST endpoint with Authorization: Bearer <intent or temp_token>. Idempotent. Used by the handoff page when the user dismisses the confirmation.

curl -X POST https://api.hoody.icu/api/v1/auth/intent/cancel \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

await client.api.authentication.oauthCancelIntent();

No content

`POST /api/v1/auth/launch/initiate`

POST endpoint that issues a one-shot launch ticket bound to the request Origin header. The frontend navigates the popup to the returned launch_url, which consumes the ticket and runs the existing PKCE-protected OAuth flow with state_id + opener_origin plumbed through.

Request Body

Name	Type	Required	Description
`provider`	string	Yes	One of: `github`, `google`.
`code_challenge`	string	Yes	PKCE `code_challenge` (43 chars).
`state_id`	string	Yes	UUID v4 per attempt.

curl -X POST https://api.hoody.icu/api/v1/auth/launch/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "state_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

await client.api.authentication.oauthLaunchInitiate({
  provider: 'github',
  code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
  state_id: '550e8400-e29b-41d4-a716-446655440000',
});

{
  "statusCode": 200,
  "data": {
    "launch_url": "https://api.hoody.icu/api/v1/auth/launch/start?ticket=5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c"
  }
}

`POST /api/v1/auth/resend-verification`

Resend the email verification link. Always returns success to prevent email enumeration.

Request Body

Name	Type	Required	Description
`email`	string	Yes	Email address to resend verification to.

curl -X POST https://api.hoody.icu/api/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{ "email": "john.doe@example.com" }'

await client.api.authentication.resendVerification({ email: 'john.doe@example.com' });

{
  "statusCode": 200,
  "message": "If an account matches that email, a verification link has been sent"
}

`POST /api/v1/auth/reset-password`

Set a new password using the reset token from the password reset email.

Request Body

Name	Type	Required	Description
`token`	string	Yes	Password reset token from the email link (64 chars).
`password`	string	Yes	New password (12-128 chars).

curl -X POST https://api.hoody.icu/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "password": "NewSecurePassword456!"
  }'

await client.api.authentication.resetPassword({
  token: '5b8e...9b0c',
  password: 'NewSecurePassword456!',
});

{
  "statusCode": 200,
  "message": "Password has been reset"
}

{
  "statusCode": 400,
  "message": "Invalid or expired reset token"
}

`POST /api/v1/auth/signup`

Create a new account with email and password. A verification email will be sent. Account is not active until email is verified.

Request Body

Name	Type	Required	Description
`email`	string	Yes	Email address for the new account.
`password`	string	Yes	Password (12-128 chars, must include uppercase, lowercase, number, special char).
`region`	string	No	Optional preferred server region (e.g. `eu-west`). Auto-assigned by GeoIP if omitted.
`invite_code`	string	No	Optional invite code (“coupon”). Memorized (hash-only) and applied automatically after email verification.

curl -X POST https://api.hoody.icu/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "password": "SecurePass123!",
    "region": "eu-west"
  }'

await client.api.authentication.signup({
  email: 'new.user@example.com',
  password: 'SecurePass123!',
  region: 'eu-west',
});

{
  "statusCode": 200,
  "message": "Account created. Check your email to verify the address.",
  "data": {
    "email": "new.user@example.com"
  }
}

{
  "statusCode": 400,
  "message": "Password must be at least 12 characters and include uppercase, lowercase, number, and special character"
}

{
  "statusCode": 403,
  "message": "Signups are currently disabled on this instance"
}

`POST /api/v1/auth/verify-email`

Verify the email address using the token from the verification email. Default response returns full login credentials. When response_mode=intent + code_challenge are provided, returns an opaque auth_intent_token for PKCE exchange (hosted auth UI flow). If 2FA is enabled on the account, returns requires_2fa + temp_token instead. On success, the login response includes an identity_claim (see Identity claims).

Request Body

Name	Type	Required	Description
`token`	string	Yes	Verification token from the email link (64 chars).
`response_mode`	string	No	`intent` or `tokens`.
`code_challenge`	string	No	PKCE `code_challenge`. Required when `response_mode=intent`.

curl -X POST https://api.hoody.icu/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "5b8e7d0c4b1f4a2c9d3a7e6f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c"
  }'

await client.api.authentication.verifyEmail({
  token: '5b8e...9b0c',
});

{
  "statusCode": 200,
  "message": "Email verified",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-11-28T20:19:00.000Z",
    "expires_in": 86400,
    "refresh_expires_at": "2025-12-04T20:19:00.000Z",
    "refresh_expires_in": 604800,
    "identity_claim": {
      "kid": "v1",
      "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0Mzg4MjAwMCwia2lkIjoidjEifQ",
      "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
    },
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "new_user",
      "alias": "New User",
      "email": "new.user@example.com",
      "is_admin": false,
      "email_verified": true,
      "signup_method": "email",
      "avatar_url": null,
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z"
    }
  }
}

{
  "statusCode": 400,
  "message": "Invalid or expired verification token"
}

Current user and session

`GET /api/v1/users/auth/me`

Retrieve the profile of the currently authenticated user. Works with JWT, auth token, or Basic authentication. When authenticated with an auth token, response includes data.auth_token introspection details (permissions and realm restrictions). This endpoint works even for banned users (read-only access). When authenticated with an auth token that lacks the resources.read_account permission, the response is reduced to identity fields (id, username, alias, public_key, timestamps); email and other account PII are omitted.

This endpoint takes no parameters.

curl -X GET https://api.hoody.icu/api/v1/users/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

await client.api.authentication.getCurrentUser();

{
  "statusCode": 200,
  "message": "Current user retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "email": "john.doe@example.com",
    "alias": "John Doe",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "is_admin": false,
    "is_banned": false,
    "email_verified": true,
    "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
    "signup_method": "github",
    "free_tier_unlocked": true,
    "free_tier_unlocked_at": "2026-06-24T10:00:00.000Z",
    "free_tier_unlock_source": "invite_code",
    "onboarding": { "hub_tour_v1": "2026-06-30T10:00:00.000Z" },
    "metadata": { "department": "Engineering" },
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "pending_pool_invitations": 0
  }
}

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.

`GET /api/v1/users/me`

This endpoint takes no parameters.

curl -X GET https://api.hoody.icu/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

await client.api.authentication.getCurrentUserAlias();

{
  "statusCode": 200,
  "message": "Current user retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "email": "john.doe@example.com",
    "alias": "John Doe",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "is_admin": false,
    "is_banned": false,
    "email_verified": true,
    "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
    "signup_method": "github",
    "free_tier_unlocked": true,
    "free_tier_unlocked_at": "2026-06-24T10:00:00.000Z",
    "free_tier_unlock_source": "invite_code",
    "onboarding": { "hub_tour_v1": "2026-06-30T10:00:00.000Z" },
    "metadata": { "department": "Engineering" },
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "pending_pool_invitations": 0
  }
}

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.

`POST /api/v1/users/auth/login`

Authenticate with username and password to receive a JWT access token (expires in 1 day) and a refresh token (expires in 7 days). Use the access token in the Authorization header for subsequent requests: Authorization: Bearer <token>. On success, the response also includes an identity_claim proving the login to third parties — see Identity claims.

Request Body

Name	Type	Required	Description
`username`	string	No	Username (alternative to `email`).
`email`	string	No	Email address (alternative to `username`).
`password`	string	Yes	Account password (8-128 chars).
`response_mode`	string	No	`intent` or `tokens`.
`code_challenge`	string	No	PKCE challenge (required when `response_mode=intent`).

curl -X POST https://api.hoody.icu/api/v1/users/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "SecurePassword123!"
  }'

await client.api.authentication.login({
  username: 'john_doe',
  password: 'SecurePassword123!',
});

{
  "statusCode": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-11-28T20:19:00.000Z",
    "expires_in": 86400,
    "refresh_expires_at": "2025-12-04T20:19:00.000Z",
    "refresh_expires_in": 604800,
    "identity_claim": {
      "kid": "v1",
      "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0Mzg4MjAwMCwia2lkIjoidjEifQ",
      "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
    },
    "client_ip": "192.168.1.100",
    "recent_login_ips": [
      { "ip": "192.168.1.100", "timestamp": "2025-01-15T10:30:00.000Z" },
      { "ip": "10.0.0.5", "timestamp": "2025-01-14T09:15:00.000Z" }
    ],
    "auth_token_count": 2,
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "john_doe",
      "alias": "John Doe",
      "email": "john.doe@example.com",
      "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
      "is_admin": false,
      "is_banned": false,
      "email_verified": true,
      "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
      "signup_method": "github",
      "metadata": {},
      "free_tier_unlocked": true,
      "free_tier_unlocked_at": "2026-06-24T10:00:00.000Z",
      "free_tier_unlock_source": "invite_code",
      "onboarding": {},
      "created_at": "2024-12-01T10:00:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  }
}

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.

{
  "statusCode": 401,
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password"
}

Error Code	Title	Description	Resolution
`INVALID_CREDENTIALS`	Invalid credentials	The provided username/email or password is incorrect.	Verify your credentials and try again, or use the password reset feature.
`EMAIL_NOT_VERIFIED`	Email not verified	Returned when the password is correct but the account’s email has not been verified yet. Reachable only after bcrypt confirms the password, so it is not an enumeration oracle. Response carries `data.email` so the client can offer a ‘resend verification email’ CTA without re-prompting.	Complete email verification by clicking the link sent to your inbox, or call `/auth/resend-verification` to receive a new link, or complete a password reset which also implicitly verifies the email.

`POST /api/v1/users/auth/logout`

Log out the current user. Creates an audit log entry. In a stateless JWT setup, the client should discard the token. This endpoint works even for banned users.

curl -X POST https://api.hoody.icu/api/v1/users/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

await client.api.authentication.logout();

{
  "statusCode": 200,
  "message": "Logout successful"
}

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.

`POST /api/v1/users/auth/refresh`

Exchange a valid refresh token for a new access token and a new refresh token. Send the refresh token in the Authorization header as Authorization: Bearer <refreshToken>, or in the request body.

Request Body

Name	Type	Required	Description
`refreshToken`	string	Yes	Valid refresh token from previous login or refresh.

curl -X POST https://api.hoody.icu/api/v1/users/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'

await client.api.authentication.refreshToken({
  refreshToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
});

{
  "statusCode": 200,
  "message": "Token refreshed successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-11-28T20:19:00.000Z",
    "expires_in": 86400,
    "refresh_expires_at": "2025-12-04T20:19:00.000Z",
    "refresh_expires_in": 604800
  }
}

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.

`POST /api/v1/users/auth/identity-claim`

Mint a fresh, audience-bound identity claim for the authenticated caller without a re-login. First-party JWT sessions only — auth tokens, HTTP Basic, and impersonated sessions are rejected (403). The claim proves “Hoody authenticated this user” to the audience named in the request; third parties verify it offline against GET /api/v1/meta/public-key. Claim lifetime is clamped to [60s, min(server ceiling — default 24h, remaining JWT lifetime)], default 1 hour. When the underlying JWT has fewer than 60 seconds of validity remaining, the endpoint returns 400 REFRESH_REQUIRED. Dual rate limits apply (per-caller refresh budget and global issuance budget). See Identity claims.

Request Body

Name	Type	Required	Description
`audience`	string	Yes	Consumer identifier this claim is bound to (e.g. your app hostname). Printable ASCII without whitespace or double quotes. Verifiers reject the claim unless they expect exactly this audience.
`expires_in`	integer	No	Requested claim lifetime in seconds. Clamped to `[60, min(server ceiling, remaining JWT lifetime)]`. Default: server-configured (1h).

curl -X POST https://api.hoody.icu/api/v1/users/auth/identity-claim \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "myapp.example.com",
    "expires_in": 3600
  }'

await client.api.authentication.api_issueIdentityClaim({
  audience: 'myapp.example.com',
  expires_in: 3600,
});

{
  "statusCode": 200,
  "message": "Identity claim issued",
  "data": {
    "identity_claim": {
      "kid": "v1",
      "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0MTI5MzYwMCwia2lkIjoidjEiLCJhdWQiOiJteWFwcC5leGFtcGxlLmNvbSJ9",
      "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
    },
    "expires_in": 3600,
    "expires_at": "2025-01-15T11:19:00.000Z",
    "audience": "myapp.example.com"
  }
}

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed: audience is required"
}

{
  "statusCode": 401,
  "error": "UNAUTHORIZED",
  "message": "Caller session is not a first-party JWT"
}

{
  "statusCode": 403,
  "error": "FORBIDDEN",
  "message": "Identity claims can only be issued to first-party JWT sessions"
}

{
  "statusCode": 503,
  "error": "SIGNING_NOT_CONFIGURED",
  "message": "Response signing is not configured on this API instance"
}

Two-factor authentication

`GET /api/v1/users/auth/2fa/status`

Check the current 2FA status for the authenticated user, including whether it is enabled and how many backup codes remain.

This endpoint takes no parameters.

curl -X GET https://api.hoody.icu/api/v1/users/auth/2fa/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

await client.api.tfa.getStatus();

{
  "statusCode": 200,
  "message": "2FA status retrieved",
  "data": {
    "enabled": true,
    "verified": true,
    "enabled_at": "2025-01-14T21:00:00.000Z",
    "backup_codes_remaining": 8,
    "require_for_tokens": true
  }
}

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required",
  "data": {
    "attempts_remaining": 3
  }
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.

`POST /api/v1/users/auth/2fa/setup`

Begin 2FA setup. Requires the current password for verification. Returns a QR code for the authenticator app and backup codes. Save the backup codes securely — they are shown only once.

Request Body

Name	Type	Required	Description
`password`	string	Yes	Current account password for verification (8-128 chars).

curl -X POST https://api.hoody.icu/api/v1/users/auth/2fa/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "password": "CorrectHorseBattery!9" }'

await client.api.tfa.setup({ password: 'CorrectHorseBattery!9' });

{
  "statusCode": 200,
  "message": "2FA setup initiated",
  "data": {
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "manual_entry_key": "JBSWY3DPEHPK3PXP",
    "backup_codes": [
      "a1b2c3d4e5",
      "f6g7h8i9j0",
      "k1l2m3n4o5",
      "p6q7r8s9t0",
      "u1v2w3x4y5",
      "z6a7b8c9d0",
      "e1f2g3h4i5",
      "j6k7l8m9n0",
      "o1p2q3r4s5",
      "t6u7v8w9x0"
    ]
  }
}

{
  "statusCode": 400,
  "error": "INCORRECT_PASSWORD",
  "message": "Incorrect password"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.
`INCORRECT_PASSWORD`	Incorrect password	The provided password does not match the account password.	Verify your password and try again.
`TWOFACTOR_ALREADY_ENABLED`	2FA already enabled	Two-factor authentication is already enabled for this account.	Disable 2FA first if you want to set it up again.

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.

`POST /api/v1/users/auth/2fa/verify-setup`

Verify and complete 2FA setup by providing the first code from your authenticator app. This confirms the setup is working correctly. On success, all sessions are revoked and a fresh token / refreshToken pair is returned (sessions_revoked: true). Adopt the new tokens to keep the current session alive.

Request Body

Name	Type	Required	Description
`code`	string	Yes	6-digit code from authenticator app.

curl -X POST https://api.hoody.icu/api/v1/users/auth/2fa/verify-setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

await client.api.tfa.verifySetup({ code: '123456' });

{
  "statusCode": 200,
  "message": "2FA successfully enabled. All other sessions have been signed out.",
  "data": {
    "enabled": true,
    "enabled_at": "2025-01-14T21:00:00.000Z",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessions_revoked": true
  }
}

{
  "statusCode": 400,
  "error": "INVALID_OTP_CODE",
  "message": "Invalid or expired 2FA code"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`TWOFACTOR_NOT_VERIFIED`	2FA setup not verified	2FA setup was initiated but not yet verified.	Complete the setup by verifying your first code.

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required",
  "data": {
    "attempts_remaining": 3
  }
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.

`POST /api/v1/users/auth/2fa/verify`

Complete login by verifying a 2FA code. Use the temp_token from the login response and provide either a 6-digit OTP code or a backup code. On success, the response includes a fresh token / refreshToken pair AND an identity_claim proving the login to third parties — see Identity claims.

Request Body

Name	Type	Required	Description
`temp_token`	string	No	Temporary token from login response (valid for 5 minutes). Alternatively pass it as `Authorization: Bearer` header.
`code`	string	Yes	6-digit OTP code from authenticator app OR 10-character backup code.
`response_mode`	string	No	`intent` or `tokens`.

curl -X POST https://api.hoody.icu/api/v1/users/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "temp_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "code": "123456"
  }'

await client.api.tfa.verify({
  temp_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  code: '123456',
});

{
  "statusCode": 200,
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "identity_claim": {
      "kid": "v1",
      "payload_b64": "eyJzdWIiOiJhMWIyYzNkNGU1ZjY3ODkwMTIzNDU2NzgiLCJ1c2VybmFtZSI6ImFsaWNlIiwidHlwZSI6InVzZXIiLCJpYXQiOjE3NDEyOTAwMDAsImV4cCI6MTc0Mzg4MjAwMCwia2lkIjoidjEifQ",
      "signature_hex": "abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef1234abcdef12"
    },
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "alias": "John Doe"
    }
  }
}

{
  "statusCode": 400,
  "error": "INVALID_OTP_CODE",
  "message": "Invalid or expired 2FA code"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`INVALID_BACKUP_CODE`	Invalid backup code	The provided backup code is incorrect or has already been used.	Verify the backup code is correct and has not been used previously.
`INVALID_TEMP_TOKEN`	Invalid temporary token	The temporary token from login has expired or is invalid.	Log in again to get a new temporary token.
`DEVICE_BINDING_GONE`	Device authorization no longer pending	The device-flow partial token references an authorization attempt that expired, was denied, was superseded by re-entering the user code, or was already completed. Retrying the OTP cannot succeed.	Return to the device verification page and re-enter the code shown in the terminal (or restart the login from the terminal).

{
  "statusCode": 401,
  "error": "INVALID_OTP_CODE",
  "message": "Invalid or expired 2FA code",
  "data": {
    "attempts_remaining": 3
  }
}

Error Code	Title	Description	Resolution
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`INVALID_BACKUP_CODE`	Invalid backup code	The provided backup code is incorrect or has already been used.	Verify the backup code is correct and has not been used previously.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.

`POST /api/v1/users/auth/2fa/backup-codes/regenerate`

Generate new backup codes (invalidates all existing ones). Requires password and current OTP code for security. Save the new codes securely — they are shown only once.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`password`	string	Yes	Current account password (8-128 chars).
`code`	string	Yes	6-digit OTP code from authenticator app.

curl -X POST https://api.hoody.icu/api/v1/users/auth/2fa/backup-codes/regenerate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "CorrectHorseBattery!9",
    "code": "123456"
  }'

await client.api.tfa.regenerateBackupCodes({
  password: 'CorrectHorseBattery!9',
  code: '123456',
});

{
  "statusCode": 200,
  "message": "Backup codes regenerated",
  "data": {
    "backup_codes": [
      "a1b2c3d4e5",
      "f6g7h8i9j0",
      "k1l2m3n4o5",
      "p6q7r8s9t0",
      "u1v2w3x4y5",
      "z6a7b8c9d0",
      "e1f2g3h4i5",
      "j6k7l8m9n0",
      "o1p2q3r4s5",
      "t6u7v8w9x0"
    ]
  }
}

{
  "statusCode": 400,
  "error": "INCORRECT_PASSWORD",
  "message": "Incorrect password"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.
`INCORRECT_PASSWORD`	Incorrect password	The provided password does not match the account password.	Verify your password and try again.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`TWOFACTOR_NOT_ENABLED`	2FA not enabled	Two-factor authentication is not enabled for this account.	Set up 2FA first using the setup endpoint.

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required",
  "data": {
    "attempts_remaining": 3
  }
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.

`PUT /api/v1/users/auth/2fa/token-gate`

Enable or disable the OTP requirement for token-mutation operations. Disabling requires both password and OTP (security downgrade requires primary-factor reauth).

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`enabled`	boolean	Yes	`true` = require OTP for token mutations (default); `false` = skip OTP gate.
`password`	string	No	Required when setting `enabled=false`.
`otp_code`	string	No	TOTP code or backup code. Required when setting `enabled=false`.

curl -X PUT https://api.hoody.icu/api/v1/users/auth/2fa/token-gate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

await client.api.tfa.setTokenGate({ enabled: true });

{
  "statusCode": 200,
  "message": "Token gate updated",
  "data": {
    "require_for_tokens": true
  }
}

{
  "statusCode": 400,
  "error": "OTP_REQUIRED",
  "message": "2FA verification required for this operation"
}

Error Code	Title	Description	Resolution
`OTP_REQUIRED`	2FA verification required	This operation requires 2FA verification because your account has 2FA enabled.	Provide an `otp_code` field with a valid TOTP code or backup code.
`TWOFACTOR_NOT_ENABLED`	2FA not enabled	Two-factor authentication is not enabled for this account.	Set up 2FA first using the setup endpoint.

{
  "statusCode": 401,
  "error": "INVALID_OTP_CODE",
  "message": "Invalid or expired 2FA code"
}

Error Code	Title	Description	Resolution
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`INCORRECT_PASSWORD`	Incorrect password	The provided password does not match the account password.	Verify your password and try again.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.

`DELETE /api/v1/users/auth/2fa`

Disable 2FA for the account. Requires both the current password and a valid OTP code (or backup code). On success, all sessions are revoked and a fresh token / refreshToken pair is returned (sessions_revoked: true). Adopt the new tokens to keep the current session alive.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`password`	string	Yes	Current account password (8-128 chars).
`code`	string	Yes	6-digit OTP code from authenticator app OR backup code.

curl -X DELETE https://api.hoody.icu/api/v1/users/auth/2fa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "CorrectHorseBattery!9",
    "code": "123456"
  }'

await client.api.tfa.disable({
  password: 'CorrectHorseBattery!9',
  code: '123456',
});

{
  "statusCode": 200,
  "message": "2FA successfully disabled. All other sessions have been signed out.",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessions_revoked": true
  }
}

{
  "statusCode": 400,
  "error": "INVALID_OTP_CODE",
  "message": "Invalid or expired 2FA code"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`MISSING_REQUIRED_FIELD`	Required field missing	One or more required fields are missing from the request.	Include all required fields as specified in the API documentation.
`INCORRECT_PASSWORD`	Incorrect password	The provided password does not match the account password.	Verify your password and try again.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`INVALID_BACKUP_CODE`	Invalid backup code	The provided backup code is incorrect or has already been used.	Verify the backup code is correct and has not been used previously.
`TWOFACTOR_NOT_ENABLED`	2FA not enabled	Two-factor authentication is not enabled for this account.	Set up 2FA first using the setup endpoint.

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "message": "Authentication token required",
  "data": {
    "attempts_remaining": 3
  }
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the `Authorization` header as `Bearer <token>`.
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again or refreshing your session.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired.	Generate a new code from your authenticator app and try again.
`INVALID_BACKUP_CODE`	Invalid backup code	The provided backup code is incorrect or has already been used.	Verify the backup code is correct and has not been used previously.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many failed attempts. Account locked for 15 minutes.",
  "data": {
    "lockout_seconds": 900
  }
}

Error Code	Title	Description	Resolution
`TWOFACTOR_RATE_LIMIT`	2FA verification locked	Too many failed 2FA verification attempts. Account is temporarily locked.	Wait for the lockout period to expire (15 minutes) before trying again.