Overview

The API Tokens API provides programmatic access to create, manage, and inspect long-lived authentication tokens on the Hoody platform. Use these endpoints to mint tokens with fine-grained permissions, restrict them by IP or realm, rotate secrets by copying, and enforce 2FA verification on sensitive operations. Token values are only returned once at creation or copy time and are never retrievable afterwards.

Note

Token creation, copy, realm mutation, update, and delete operations require a valid 2FA otp_code when the account has 2FA enabled and the caller is authenticating via JWT.

Tokens

GET /api/v1/auth/tokens

List all auth tokens for the authenticated user. Token values are never included in the response.

This endpoint takes no parameters.

cURL

curl -X GET https://api.hoody.com/api/v1/auth/tokens \
  -H "Authorization: Bearer <token>"

SDK

const { data } = await client.api.authTokens.listIterator();

200 Response

{
  "statusCode": 200,
  "message": "Auth tokens retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "alias": "Production API Key",
      "prefix": "hdy_",
      "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
      "realm_ids": [],
      "allow_no_realm": true,
      "expires_at": "2025-12-31T23:59:59.000Z",
      "is_enabled": true,
      "vault_access": true,
      "event_access": true,
      "last_used_at": "2025-10-28T12:00:00.000Z",
      "last_used_ip": "198.51.100.1",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T14:45:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439022",
      "alias": "Development Token",
      "prefix": "hdy_",
      "ip_whitelist": ["*"],
      "realm_ids": ["507f1f77bcf86cd799439011"],
      "allow_no_realm": false,
      "expires_at": null,
      "is_enabled": true,
      "vault_access": false,
      "event_access": true,
      "last_used_at": null,
      "last_used_ip": null,
      "created_at": "2025-01-10T08:00:00.000Z",
      "updated_at": "2025-01-10T08:00:00.000Z"
    }
  ],
  "truncated": false
}

401 Response

{
  "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

GET /api/v1/auth/tokens/{id}

Get details of a specific auth token. The token value is not included.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the token

cURL

curl -X GET https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>"

SDK

const { data } = await client.api.authTokens.get({
  id: "507f1f77bcf86cd799439011"
});

200 Response

{
  "statusCode": 200,
  "message": "Auth token retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": [],
    "allow_no_realm": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

400 Response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401 Response

{
  "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

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Error Code	Title	Description	Resolution
TOKEN_NOT_FOUND	Authentication token not found	The requested authentication token does not exist or has been deleted	Verify the token ID is correct and that the token still exists

GET /api/v1/auth/tokens/me

Return metadata, permissions, and realm restrictions for the currently authenticated auth token. This endpoint is allowed on the base api.hoody.com domain for realm-scoped tokens to bootstrap realm discovery.

This endpoint takes no parameters.

cURL

curl -X GET https://api.hoody.com/api/v1/auth/tokens/me \
  -H "Authorization: Bearer <token>"

SDK

const { data } = await client.api.authTokens.getCurrent();

200 Response

{
  "statusCode": 200,
  "message": "Current auth token retrieved successfully",
  "data": {
    "token": {
      "id": "507f1f77bcf86cd799439011",
      "alias": "External Customer Token",
      "prefix": "hdy_",
      "ip_whitelist": ["*"],
      "realm_ids": ["507f1f77bcf86cd799439012"],
      "allow_no_realm": false,
      "permissions": {
        "containers": { "read": true, "create": true },
        "resources": { "realms": true }
      },
      "expires_at": null,
      "is_enabled": true,
      "vault_access": false,
      "event_access": true,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "restrictions": {
      "has_realm_restrictions": true,
      "requires_realm_scope": true,
      "allowed_realm_ids": ["507f1f77bcf86cd799439012"],
      "allow_no_realm": false,
      "active_realm_id": "507f1f77bcf86cd799439012"
    }
  }
}

401 Response

{
  "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

403 Response

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

POST /api/v1/auth/tokens

Create a new long-term authentication token with optional IP restrictions, realm restrictions, expiration, and a fine-grained permission set.

This endpoint takes no path, query, or header parameters.

Request Body

Field	Type	Required	Description
alias	string	No	User-friendly alias. Allowed characters: letters, numbers, spaces, underscores, hyphens (max 254). If omitted, a random animal name is generated.
public_key	string | null	No	Optional ED25519 public key as 64-character hexadecimal string. Pass null to clear.
public_storage	object | null	No	Arbitrary public JSON profile object (max 64KB serialized). Pass null to clear.
ip_whitelist	array | string	No	IP allowlist. Accepts an array of IPv4 addresses/CIDR ranges, a comma-separated string, or "*" wildcard. Defaults to "*".
permission_template	string	No	Permission template name. If provided, takes precedence over permissions. One of: full_access, external_customer, dev_team, finance_team, read_only.
permissions	object	No	Fine-grained permissions. Any missing permission path defaults to false (deny).
realm_ids	array	No	Realm IDs this token is restricted to. If provided, the token can only be used on these realm subdomains.
allow_no_realm	boolean	No	Whether the token can be used without a realm scope. Defaults to true. Set to false for strict sub-account tokens.
vault_access	boolean	No	Whether the token can access vault endpoints. Defaults to false.
event_access	boolean	No	Whether the token can access event streams and event history. Defaults to true.
expires_at	string | number	No	Expiration as ISO 8601 timestamp, Unix timestamp (seconds or milliseconds), "today", or "tomorrow". Omit for a non-expiring token.
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled on the account.

cURL

curl -X POST https://api.hoody.com/api/v1/auth/tokens \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production API Key",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Production Integrations",
      "tier": "gold"
    },
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "vault_access": true,
    "expires_at": 1767225599000
  }'

SDK

const { data } = await client.api.authTokens.create({
  data: {
    alias: "Production API Key",
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    public_storage: {
      display_name: "Production Integrations",
      tier: "gold"
    },
    ip_whitelist: ["192.168.1.0/24", "10.0.0.1"],
    vault_access: true,
    expires_at: 1767225599000
  }
});

201 Response

{
  "statusCode": 201,
  "message": "Auth token created successfully",
  "data": {
    "token": "hdy_a1b2c3d4e5f67890abcdef1234567890",
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {},
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": [],
    "allow_no_realm": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

Danger

The token field contains the full secret value and is returned only once. Store it immediately and never request it again.

400 Response

{
  "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
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
INVALID_ALIAS_FORMAT	Invalid alias format	Token alias must contain only letters, numbers, spaces, underscores, and hyphens	Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (_), and hyphens (-)
INVALID_IP_FORMAT	Invalid IP address format	IP whitelist must contain valid IPv4 addresses or CIDR ranges	Provide valid IPv4 addresses (e.g., 192.168.1.1) or CIDR ranges (e.g., 192.168.1.0/24), or use * for all IPs
INVALID_REALM_ID_FORMAT	Invalid realm ID format	Realm IDs must be 24-character hexadecimal strings	Ensure all realm IDs are valid 24-character hex strings (e.g., 507f1f77bcf86cd799439011)
INVALID_EXPIRATION_FORMAT	Invalid expiration format	Expiration must be an ISO 8601 date, Unix timestamp, today, tomorrow, or null	Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), today, tomorrow, or null for non-expiring
INVALID_PUBLIC_KEY_FORMAT	Invalid public key format	Public key must be exactly 64 hexadecimal characters (ED25519 format)	Provide a valid 64-character ED25519 public key in hexadecimal format
PUBLIC_STORAGE_TOO_LARGE	Public storage exceeds size limit	public_storage must not exceed 64KB serialized JSON	Reduce the size of the public storage payload and retry
EXPIRATION_IN_PAST	Expiration date in the past	The expiration date cannot be in the past	Provide a future date for token expiration

401 Response

{
  "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

409 Response

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}

Error Code	Title	Description	Resolution
DUPLICATE_ALIAS	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

PATCH /api/v1/auth/tokens/{id}

Update an existing auth token. Any field omitted from the request body is left unchanged. Provide null to clear expires_at, public_key, or public_storage.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the token to update

Request Body

Field	Type	Required	Description
alias	string	No	New token alias (letters, numbers, spaces, underscores, hyphens; max 254)
public_key	string | null	No	New ED25519 public key (64 hex chars), or null to clear
public_storage	object | null	No	New public profile payload (max 64KB), or null to clear
ip_whitelist	array | string	No	New IP allowlist (array, comma-separated string, or *)
permissions	object	No	Replacement permission set; any omitted path defaults to false (deny)
realm_ids	array	No	Replacement realm restriction list
allow_no_realm	boolean	No	Whether the token can be used without a realm scope
vault_access	boolean	No	Whether the token can access vault endpoints
event_access	boolean	No	Whether the token can access event streams and event history
expires_at	string | number | null	No	New expiration as ISO timestamp, Unix timestamp, today, tomorrow, or null to make non-expiring
is_enabled	boolean	No	Enable or disable the token
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled on the account.

cURL

curl -X PATCH https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Updated Production Key",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Updated Profile",
      "links": { "website": "https://example.com" }
    },
    "ip_whitelist": ["*"],
    "vault_access": false,
    "expires_at": null,
    "is_enabled": false
  }'

SDK

const { data } = await client.api.authTokens.update({
  id: "507f1f77bcf86cd799439011",
  data: {
    alias: "Updated Production Key",
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    public_storage: {
      display_name: "Updated Profile",
      links: { website: "https://example.com" }
    },
    ip_whitelist: ["*"],
    vault_access: false,
    expires_at: null,
    is_enabled: false
  }
});

200 Response

{
  "statusCode": 200,
  "message": "Auth token updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Updated Production Key",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {},
    "ip_whitelist": ["*"],
    "realm_ids": [],
    "allow_no_realm": true,
    "expires_at": null,
    "is_enabled": false,
    "vault_access": false,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

400 Response

{
  "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
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
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
INVALID_ALIAS_FORMAT	Invalid alias format	Token alias must contain only letters, numbers, spaces, underscores, and hyphens	Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (_), and hyphens (-)
INVALID_IP_FORMAT	Invalid IP address format	IP whitelist must contain valid IPv4 addresses or CIDR ranges	Provide valid IPv4 addresses (e.g., 192.168.1.1) or CIDR ranges (e.g., 192.168.1.0/24), or use * for all IPs
INVALID_REALM_ID_FORMAT	Invalid realm ID format	Realm IDs must be 24-character hexadecimal strings	Ensure all realm IDs are valid 24-character hex strings (e.g., 507f1f77bcf86cd799439011)
INVALID_EXPIRATION_FORMAT	Invalid expiration format	Expiration must be an ISO 8601 date, Unix timestamp, today, tomorrow, or null	Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), today, tomorrow, or null for non-expiring
INVALID_PUBLIC_KEY_FORMAT	Invalid public key format	Public key must be exactly 64 hexadecimal characters (ED25519 format)	Provide a valid 64-character ED25519 public key in hexadecimal format
PUBLIC_STORAGE_TOO_LARGE	Public storage exceeds size limit	public_storage must not exceed 64KB serialized JSON	Reduce the size of the public storage payload and retry
EXPIRATION_IN_PAST	Expiration date in the past	The expiration date cannot be in the past	Provide a future date for token expiration

401 Response

{
  "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

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Error Code	Title	Description	Resolution
TOKEN_NOT_FOUND	Authentication token not found	The requested authentication token does not exist or has been deleted	Verify the token ID is correct and that the token still exists

409 Response

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}

Error Code	Title	Description	Resolution
DUPLICATE_ALIAS	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

POST /api/v1/auth/tokens/{id}/copy

Copy an existing auth token’s configuration (permissions, realm restrictions, IP whitelist, public profile) into a new token with a freshly generated secret value. Useful for secret rotation without changing scopes.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the token to copy

Request Body

Field	Type	Required	Description
alias	string	No	Alias for the copied token (max 254). If omitted, a deterministic alias like "<source> copy" is generated.
expires_at	string | number | null	No	Override the source expiration. Accepts ISO 8601 timestamp, Unix timestamp, today, tomorrow, or null to make non-expiring.
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled on the account.

cURL

curl -X POST https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011/copy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production API Key Copy"
  }'

SDK

const { data } = await client.api.authTokens.copy({
  id: "507f1f77bcf86cd799439011",
  data: {
    alias: "Production API Key Copy"
  }
});

201 Response

{
  "statusCode": 201,
  "message": "Auth token copied successfully",
  "data": {
    "token": "hdy_f0e1d2c3b4a5968778695a4b3c2d1e0f1234567890abcdef",
    "id": "507f1f77bcf86cd799439099",
    "alias": "Production API Key Copy",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": ["507f1f77bcf86cd799439011"],
    "allow_no_realm": false,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-20T08:30:00.000Z",
    "updated_at": "2025-01-20T08:30:00.000Z"
  }
}

Danger

The token field contains the full secret value of the new copy and is returned only once. Store it immediately.

400 Response

{
  "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
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
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
INVALID_ALIAS_FORMAT	Invalid alias format	Token alias must contain only letters, numbers, spaces, underscores, and hyphens	Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (_), and hyphens (-)
INVALID_EXPIRATION_FORMAT	Invalid expiration format	Expiration must be an ISO 8601 date, Unix timestamp, today, tomorrow, or null	Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), today, tomorrow, or null for non-expiring
EXPIRATION_IN_PAST	Expiration date in the past	The expiration date cannot be in the past	Provide a future date for token expiration

401 Response

{
  "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

403 Response

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Error Code	Title	Description	Resolution
TOKEN_NOT_FOUND	Authentication token not found	The requested authentication token does not exist or has been deleted	Verify the token ID is correct and that the token still exists

409 Response

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}

Error Code	Title	Description	Resolution
DUPLICATE_ALIAS	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

DELETE /api/v1/auth/tokens/{id}

Permanently delete an auth token. Once deleted, the token can no longer be used for authentication.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the token

cURL

curl -X DELETE https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>"

SDK

const { data } = await client.api.authTokens.delete({
  id: "507f1f77bcf86cd799439011"
});

200 Response

{
  "statusCode": 200,
  "message": "Auth token deleted successfully"
}

400 Response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401 Response

{
  "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

403 Response

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Error Code	Title	Description	Resolution
TOKEN_NOT_FOUND	Authentication token not found	The requested authentication token does not exist or has been deleted	Verify the token ID is correct and that the token still exists

Realm management

Realm-scoped tokens are bound to one or more realm IDs. These endpoints add or remove realm bindings without rewriting the rest of the token configuration. Both operations are idempotent: re-adding an existing realm or removing a missing realm returns success without modification.

POST /api/v1/auth/tokens/{id}/add-realm

Atomically add a realm ID to an auth token.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Auth token ID

Request Body

Field	Type	Required	Description
realm_id	string	Yes	Realm ID to add to the token (24-character hex)
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled on the account.

cURL

curl -X POST https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011/add-realm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "realm_id": "507f1f77bcf86cd799439033"
  }'

SDK

const { data } = await client.api.authTokens.addRealm({
  id: "507f1f77bcf86cd799439011",
  data: {
    realm_id: "507f1f77bcf86cd799439033"
  }
});

200 Response

{
  "statusCode": 200,
  "message": "Realm added to auth token",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439033"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true, "create": true }
    },
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T11:15:00.000Z"
  }
}

400 Response

{
  "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
INVALID_REALM_ID_FORMAT	Invalid realm ID format	Realm IDs must be 24-character hexadecimal strings	Ensure all realm IDs are valid 24-character hex strings (e.g., 507f1f77bcf86cd799439011)

401 Response

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

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

POST /api/v1/auth/tokens/{id}/remove-realm

Atomically remove a realm ID from an auth token. Idempotent: removing a realm that is not currently bound returns success without modification.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Auth token ID

Request Body

Field	Type	Required	Description
realm_id	string	Yes	Realm ID to remove from the token (24-character hex)
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled on the account.

cURL

curl -X POST https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011/remove-realm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "realm_id": "507f1f77bcf86cd799439033"
  }'

SDK

const { data } = await client.api.authTokens.removeRealm({
  id: "507f1f77bcf86cd799439011",
  data: {
    realm_id: "507f1f77bcf86cd799439033"
  }
});

200 Response

{
  "statusCode": 200,
  "message": "Realm removed from auth token",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": ["507f1f77bcf86cd799439011"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true, "create": true }
    },
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T11:30:00.000Z"
  }
}

400 Response

{
  "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
INVALID_REALM_ID_FORMAT	Invalid realm ID format	Realm IDs must be 24-character hexadecimal strings	Ensure all realm IDs are valid 24-character hex strings (e.g., 507f1f77bcf86cd799439011)

401 Response

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

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Public profiles

Tokens can carry an optional ED25519 public key and an arbitrary JSON profile blob (public_storage, max 64KB). These are resolved via the public key, allowing third parties to look up a token’s public profile without holding the secret.

GET /api/v1/auth/tokens/public-profiles/{public_key}

Resolve and retrieve an auth token public profile by its ED25519 public key.

Parameters

Name	In	Type	Required	Description
public_key	path	string	Yes	ED25519 public key to resolve (64 hex characters)

cURL

curl -X GET https://api.hoody.com/api/v1/auth/tokens/public-profiles/a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234 \
  -H "Authorization: Bearer <token>"

SDK

const { data } = await client.api.authTokens.getPublicProfile({
  public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234"
});

200 Response

{
  "statusCode": 200,
  "message": "Public profile retrieved successfully",
  "data": {
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "username_hint": "acme-team",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }
}

400 Response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid public key format"
}

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
INVALID_PUBLIC_KEY_FORMAT	Invalid public key format	Public key must be exactly 64 hexadecimal characters (ED25519 format)	Provide a valid 64-character ED25519 public key in hexadecimal format

401 Response

{
  "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

404 Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}

Error Code	Title	Description	Resolution
TOKEN_NOT_FOUND	Authentication token not found	The requested authentication token does not exist or has been deleted	Verify the token ID is correct and that the token still exists

PATCH /api/v1/auth/tokens/me/public-profile

Update the currently authenticated token’s public_key and/or public_storage. Requires the resources.auth_token_public_profile permission on the token. At least one of public_key or public_storage must be provided. Pass null to clear either field.

This endpoint takes no path, query, or header parameters.

Request Body

Field	Type	Required	Description
public_key	string | null	No	New ED25519 public key (64 hex chars), or null to clear
public_storage	object | null	No	New public profile payload (max 64KB), or null to clear

cURL

curl -X PATCH https://api.hoody.com/api/v1/auth/tokens/me/public-profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "username_hint": "acme-team",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }'

SDK

const { data } = await client.api.authTokens.updatePublicProfile({
  data: {
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    public_storage: {
      username_hint: "acme-team",
      avatar: "https://cdn.example.com/avatar.png"
    }
  }
});

200 Response

{
  "statusCode": 200,
  "message": "Public profile updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "username_hint": "acme-team",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439012"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true, "create": true },
      "resources": { "realms": true, "auth_token_public_profile": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T12:00:00.000Z"
  }
}

400 Response

{
  "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
INVALID_PUBLIC_KEY_FORMAT	Invalid public key format	Public key must be exactly 64 hexadecimal characters (ED25519 format)	Provide a valid 64-character ED25519 public key in hexadecimal format
PUBLIC_STORAGE_TOO_LARGE	Public storage exceeds size limit	public_storage must not exceed 64KB serialized JSON	Reduce the size of the public storage payload and retry

401 Response

{
  "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

403 Response

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access