Authentication

Download Page (.md)

Authenticate users with the Hoody API, manage sessions, verify email addresses, and configure two-factor authentication. This page covers email/password flows, OAuth (GitHub and Google), PKCE-protected popup handoffs, email verification, password recovery, and TOTP-based 2FA.

Server discovery

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

Returns regions where free-tier servers exist, with boolean availability. This endpoint is public and requires no authentication.

curl https://api.hoody.com/api/v1/auth/available-regions

const { data } = await client.api.authentication.getAvailableRegions();

{
  "statusCode": 200,
  "data": {
    "regions": [
      {
        "region": "eu-west",
        "country": "Netherlands",
        "city": "Amsterdam",
        "available": true
      },
      {
        "region": "us-east",
        "country": "United States",
        "city": "New York",
        "available": true
      },
      {
        "region": "ap-southeast",
        "country": "Singapore",
        "city": "Singapore",
        "available": false
      }
    ]
  }
}

Signing keys

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

Returns the ED25519 public keys used by Hoody to sign API responses (X-Hoody-Signature header), identity claims issued at login, and container authorization claims. No authentication required.

Verification flow:

Fetch this endpoint once and cache the result for at least 24 hours.
Locate the key by kid from the keys[] array.
For response signatures, parse X-Hoody-Signature: t=<ts>,kid=<id>,path=<url>,sig=<hex> and verify sig against t + "." + responseBody.
For identity and container claims, verify claim.signature_hex against the UTF-8 bytes of claim.payload_b64.
If a signature references a kid not present in your cached keys, re-fetch this endpoint.

curl https://api.hoody.com/api/v1/meta/public-key

const { data } = 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>,path=<request_url>,sig=<hex>",
      "response_signed_data": "<t_value>.<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
    }
  }
}

Responses include a X-Hoody-Signature header containing the ED25519 signature in the format t=<unix_ts>,kid=<keyId>,path=<urlPath>,sig=<128-hex>.

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

OAuth authentication

All OAuth redirect endpoints use PKCE. The code_challenge (base64url SHA-256 of code_verifier) is required.

`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) or `star_check` (check for star credit). Allowed values: `login`, `star_check`.
`redirect_uri`	query	string	No	Frontend URL to redirect to after OAuth completes (must be on 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.

curl -L "https://api.hoody.com/api/v1/auth/github?intent=login&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

await client.api.authentication.githubOAuthRedirect({
  intent: "login",
  code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
});

HTTP/1.1 302 Found
Location: https://github.com/login/oauth/authorize?...

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

Handles the GitHub OAuth callback. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`code`	query	string	Yes	OAuth code returned by GitHub
`state`	query	string	Yes	State value for CSRF protection

curl -L "https://api.hoody.com/api/v1/auth/github/callback?code=acf4d2e9&state=xyz123"

await client.api.authentication.githubOAuthCallback({
  code: "acf4d2e9",
  state: "xyz123"
});

HTTP/1.1 302 Found
Location: https://app.hoody.com/oauth/complete?...

`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	No	Frontend URL to redirect to after OAuth completes
`code_challenge`	query	string	Yes	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`). Required — all OAuth flows must use PKCE post-migration.

curl -L "https://api.hoody.com/api/v1/auth/google?code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

await client.api.authentication.googleOAuthRedirect({
  code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
});

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?...

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

Handles the Google OAuth callback. Browser-only endpoint.

Parameters

Name	In	Type	Required	Description
`code`	query	string	Yes	OAuth code returned by Google
`state`	query	string	Yes	State value for CSRF protection

curl -L "https://api.hoody.com/api/v1/auth/google/callback?code=4/0AY0e-g7X&state=xyz123"

await client.api.authentication.googleOAuthCallback({
  code: "4/0AY0e-g7X",
  state: "xyz123"
});

HTTP/1.1 302 Found
Location: https://app.hoody.com/oauth/complete?...

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

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 and opener_origin plumbed through.

Request Body

Name	Type	Required	Description
`provider`	string	Yes	OAuth provider. Allowed values: `github`, `google`.
`code_challenge`	string	Yes	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`, 43–128 chars)
`state_id`	string	Yes	Per-attempt UUID v4 — plumbed through state JWT, cookie name, fragment, message filter

curl -X POST https://api.hoody.com/api/v1/auth/launch/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "state_id": "f7a3b1c9-4d2e-4a8b-9f0c-1e2d3a4b5c6d"
  }'

const { data } = await client.api.authentication.oauthLaunchInitiate({
  provider: "github",
  code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  state_id: "f7a3b1c9-4d2e-4a8b-9f0c-1e2d3a4b5c6d"
});

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

`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 -L "https://api.hoody.com/api/v1/auth/launch/start?ticket=tkt_8d7f6e5c4b3a2918"

await client.api.authentication.oauthLaunchStart({
  ticket: "tkt_8d7f6e5c4b3a2918"
});

HTTP/1.1 302 Found
Location: https://github.com/login/oauth/authorize?...

{
  "statusCode": 410,
  "error": "Gone",
  "message": "This launch ticket has already been used or has expired."
}

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

Cancel a pending OAuth AuthIntent or 2FA temp_token. Idempotent. Used by the handoff page when the user dismisses the confirmation. Send the token as Authorization: Bearer <intent or temp_token>.

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

await client.api.authentication.oauthCancelIntent();

HTTP/1.1 204 No Content

Account

`POST /api/v1/auth/signup`

Create a new account with email and password. A verification email is sent. The account is not active until the email is verified.

Request Body

Name	Type	Required	Description
`email`	string	Yes	Email address for the new account
`password`	string	Yes	Password (min 12 chars, must include uppercase, lowercase, number, and special char)
`region`	string	No	Optional preferred server region (e.g. `eu-west`). If omitted, auto-assigned by GeoIP proximity.

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

const { data } = await client.api.authentication.signup({
  email: "john.doe@example.com",
  password: "SecurePassword123!"
});

{
  "statusCode": 200,
  "message": "Account created. Please check your email to verify your address.",
  "data": {
    "email": "john.doe@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"
}

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

Authenticate with username and password to receive a JWT access token (expires in 1 day) and refresh token (expires in 7 days). Use the access token in the Authorization header for subsequent requests: Authorization: Bearer {token}.

Request Body

Name	Type	Required	Description
`username`	string	No	Username (alphanumeric, underscores, hyphens). Provide `username` or `email`.
`email`	string	No	Email address (alternative to `username`)
`password`	string	Yes	Account password. Must be at least 8 characters with uppercase, lowercase, and number.
`response_mode`	string	No	Response shape. `tokens` (default) returns access/refresh tokens. `intent` returns an opaque `auth_intent_token` for PKCE exchange. Allowed values: `intent`, `tokens`.
`code_challenge`	string	No	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`). Required when `response_mode=intent`.

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

const { data } = 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,
    "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",
      "is_admin": false,
      "is_banned": false,
      "metadata": {},
      "created_at": "2024-12-01T10:00:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  }
}

The response is signed via X-Hoody-Signature. When the user has 2FA enabled, the response includes data.requires_2fa, data.temp_token, and data.method: "totp" instead of the token pair.

{
  "statusCode": 400,
  "error": "Bad Request",
  "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": "Unauthorized",
  "message": "Invalid credentials"
}

Error Code	Title	Description	Resolution
`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
`EMAIL_NOT_VERIFIED`	Email not verified	Returned by the login endpoint 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.

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

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

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

await client.api.authentication.logout();

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

{
  "statusCode": 401,
  "error": "Unauthorized",
  "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 new refresh token. Send the refresh token in the Authorization header: Authorization: Bearer {refreshToken}.

Request Body

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

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

const { data } = 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": "Unauthorized",
  "message": "Invalid or expired refresh token"
}

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/auth/me`

Retrieve the profile of the currently authenticated user. Works with JWT, auth token, or Basic authentication. When authenticated with an auth token, the response includes data.auth_token introspection details (permissions and realm restrictions). This endpoint works even for banned users (read-only access).

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

const { data } = await client.api.authentication.getCurrentUser();

{
  "statusCode": 200,
  "message": "Current user retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "alias": "John Doe",
    "email": "john.doe@example.com",
    "is_admin": false,
    "is_banned": false,
    "email_verified": true,
    "metadata": {},
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "pending_pool_invitations": 0
  }
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "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

Email verification & password recovery

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

Verify the email address using the token from the verification email. The 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.

Request Body

Name	Type	Required	Description
`token`	string	Yes	Verification token from the email link (64 characters)
`response_mode`	string	No	Response shape. `tokens` (default) returns access/refresh tokens. `intent` returns an opaque `auth_intent_token` for PKCE exchange. Allowed values: `intent`, `tokens`.
`code_challenge`	string	No	PKCE `code_challenge` (base64url SHA-256 of `code_verifier`). Required when `response_mode=intent`.

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

const { data } = await client.api.authentication.verifyEmail({
  token: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234"
});

{
  "statusCode": 200,
  "message": "Email verified. 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,
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "john_doe",
      "alias": "John Doe",
      "email": "john.doe@example.com",
      "is_admin": false,
      "email_verified": true,
      "signup_method": "email",
      "avatar_url": null,
      "created_at": "2024-12-01T10:00:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  }
}

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

`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.com/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 exists for that email and is not yet verified, a verification link has been sent."
}

`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.com/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 exists for that email, a password reset 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 characters)
`password`	string	Yes	New password (min 12 chars)

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

await client.api.authentication.resetPassword({
  token: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
  password: "NewSecurePassword123!"
});

{
  "statusCode": 200,
  "message": "Password reset successful. You can now log in with your new password."
}

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

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.

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

const { data } = 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": "Unauthorized",
  "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
`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 backup codes securely — they are shown only once.

Request Body

Name	Type	Required	Description
`password`	string	Yes	Current account password for verification (8–128 characters)

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

const { data } = await client.api.tfa.setup({
  password: "SecurePassword123!"
});

{
  "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": "Bad Request",
  "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": "Unauthorized",
  "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 the authenticator app. This confirms the setup is working correctly.

Request Body

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

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

const { data } = await client.api.tfa.verifySetup({
  code: "482915"
});

{
  "statusCode": 200,
  "message": "2FA successfully enabled",
  "data": {
    "enabled": true,
    "enabled_at": "2025-01-14T21:00:00.000Z"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid OTP 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": "Unauthorized",
  "message": "Invalid or expired 2FA code",
  "data": {
    "attempts_remaining": 4
  }
}

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 the 2FA code. Use the temp_token from the login response and provide either a 6-digit OTP code or a backup code.

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 the authenticator app OR 10-character backup code
`response_mode`	string	No	Response shape. `tokens` (default) returns access/refresh tokens. `intent` returns an opaque `auth_intent_token` for PKCE exchange. Allowed values: `intent`, `tokens`.

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

const { data } = await client.api.tfa.verify({
  temp_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  code: "482915"
});

{
  "statusCode": 200,
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "alias": "John Doe"
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "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

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

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.

Request Body

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

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

const { data } = await client.api.tfa.regenerateBackupCodes({
  password: "SecurePassword123!",
  code: "482915"
});

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

{
  "statusCode": 400,
  "error": "Bad Request",
  "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": "Unauthorized",
  "message": "Invalid or expired 2FA code",
  "data": {
    "attempts_remaining": 4
  }
}

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

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

Enable or disable the OTP requirement for token mutation operations. Disabling requires both password and OTP.

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` (security downgrade requires primary-factor reauth)
`otp_code`	string	No	TOTP code or backup code. Required when setting `enabled=false`.

curl -X PATCH https://api.hoody.com/api/v1/users/auth/2fa/token-gate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "password": "SecurePassword123!",
    "otp_code": "482915"
  }'

const { data } = await client.api.tfa.setTokenGate({
  enabled: false,
  password: "SecurePassword123!",
  otp_code: "482915"
});

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

{
  "statusCode": 400,
  "error": "Bad Request",
  "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": "Unauthorized",
  "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) for security.

Request Body

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

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

const { data } = await client.api.tfa.disable({
  password: "SecurePassword123!",
  code: "482915"
});

{
  "statusCode": 200,
  "message": "2FA successfully disabled"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "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
`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": "Unauthorized",
  "message": "Invalid or expired 2FA code",
  "data": {
    "attempts_remaining": 4
  }
}

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