The API Tokens endpoints let you create and manage long-lived authentication tokens for programmatic access to the Hoody platform. Use these endpoints to issue scoped tokens with IP restrictions, expiration, and fine-grained permissions, and to manage their lifecycle (update, copy, add/remove realm bindings, delete).

Caution

Token secrets are only returned in the response body at creation or copy time. Store them securely — they cannot be retrieved later.

List auth tokens

Returns all auth tokens for the authenticated user. Token values are not included in the response.

cURL

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

TypeScript SDK

const tokens = await client.api.authTokens.listIterator();

Response

200

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

401

{
  "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 auth token by ID

Returns details of a specific auth token. The token value is not included in the response.

cURL

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

TypeScript SDK

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

Parameters

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

Response

200

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

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

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

{
  "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 current auth token details

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

cURL

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

TypeScript SDK

const current = await client.api.authTokens.getCurrent();

Response

200

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

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

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

Get auth token public profile by public key

Resolves and retrieves an auth token’s public profile storage by ED25519 public key.

cURL

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

TypeScript SDK

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

Parameters

Name	In	Type	Required	Description
public_key	path	string	Yes	ED25519 public key to resolve

Response

200

{
  "statusCode": 200,
  "message": "Public profile retrieved successfully",
  "data": {
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Acme Integrations",
      "website": "https://example.com"
    }
  }
}

400

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

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

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

Create a new auth token

Creates a new long-term authentication token with optional IP restrictions, expiration, and fine-grained permissions.

cURL

curl -X POST https://api.hoody.icu/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
  }'

TypeScript SDK

const result = 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
  }
});

Request Body

Field	Type	Required	Description
alias	string	No	User-friendly alias. Allowed characters: letters, numbers, spaces, underscores, hyphens. If omitted, a random animal name is generated.
public_key	string | null	No	ED25519 public key (64 hex chars) or null to clear.
public_storage	object | null	No	Public JSON profile storage (max 64KB) or null to clear.
ip_whitelist	array | string	No	Array of IPv4 addresses/CIDR ranges, comma-separated string, or * wildcard. Defaults to *.
permission_template	string	No	Permission template to apply (full_access, external_customer, dev_team, finance_team, read_only). Takes precedence over permissions.
permissions	object	No	Fine-grained permission map. Missing paths default to false.
realm_ids	array	No	Realm IDs to restrict this token to.
allow_no_realm	boolean	No	Whether the token can be used without a realm scope. Default: true.
vault_access	boolean	No	Whether the token can access user vault endpoints. Default: false.
event_access	boolean	No	Whether the token can access event streams. Default: true.
expires_at	string | number	No	ISO 8601 date, Unix timestamp, today, or tomorrow.
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

Response

201

{
  "statusCode": 201,
  "message": "Auth token created successfully",
  "data": {
    "token": "hdy_a1b2c3d4e5f67890abcdef1234567890",
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Production Integrations",
      "tier": "gold"
    },
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": [],
    "allow_no_realm": true,
    "permissions": {
      "containers": {
        "read": 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"
  }
}

400

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

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

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

Add realm to auth token

Atomically adds a realm ID to an auth token. Idempotent — if the realm is already present, returns success without modification.

cURL

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

TypeScript SDK

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

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
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

Response

200

{
  "statusCode": 200,
  "message": "Realm added to auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:00:00.000Z"
  }
}

400

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

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

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

404

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

Copy auth token

Copies an existing auth token’s configuration (permissions, realm restrictions, IP whitelist) into a new token with a new secret value.

cURL

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

TypeScript SDK

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

Parameters

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

Request Body

Field	Type	Required	Description
alias	string	No	Optional alias for the copied token. If omitted, a deterministic alias like "<source> copy" is generated.
expires_at	string | number | null	No	ISO 8601 date, Unix timestamp, today, tomorrow, or null for non-expiring. Defaults to source expiration.
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

Response

201

{
  "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,
    "permissions": {
      "containers": { "read": 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-20T08:30:00.000Z",
    "updated_at": "2025-01-20T08:30:00.000Z"
  }
}

400

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

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

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

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

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

Remove realm from auth token

Atomically removes a realm ID from an auth token. Idempotent — if the realm is not present, returns success without modification.

cURL

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

TypeScript SDK

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

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
otp_code	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

Response

200

{
  "statusCode": 200,
  "message": "Realm removed from auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": [],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:10:00.000Z"
  }
}

400

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

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

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

404

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

Update auth token

Updates an existing auth token’s alias, public key/profile storage, IP restrictions, expiration, enabled status, permissions, or realm bindings.

cURL

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

TypeScript SDK

const updated = await client.api.authTokens.update({
  id: "507f1f77bcf86cd799439011",
  data: {
    alias: "Updated Production Key",
    ip_whitelist: ["*"],
    vault_access: false,
    expires_at: null,
    is_enabled: false
  }
});

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	User-friendly alias. Allowed characters: letters, numbers, spaces, underscores, hyphens.
public_key	string | null	No	ED25519 public key (64 hex chars) or null to clear.
public_storage	object | null	No	Public JSON profile storage (max 64KB) or null to clear.
ip_whitelist	array | string	No	Array of IPv4 addresses/CIDR ranges, comma-separated string, or * wildcard.
permissions	object	No	Fine-grained permission map. Missing paths default to false.
realm_ids	array	No	Realm IDs to restrict this token to.
allow_no_realm	boolean	No	Whether the token can be used without a realm scope.
vault_access	boolean	No	Whether the token can access user vault endpoints.
event_access	boolean	No	Whether the token can access event streams and event history.
expires_at	string | number | null	No	ISO 8601 date, Unix timestamp, today, tomorrow, or null for 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 and authenticating via JWT.

Response

200

{
  "statusCode": 200,
  "message": "Auth token updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Updated Production Key",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": [],
    "allow_no_realm": true,
    "permissions": {
      "containers": { "read": 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

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

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

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

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

Update current auth token public profile

Updates the current auth token’s public_key and public_storage payload. Requires the resources.auth_token_public_profile permission on the auth token.

cURL

curl -X PATCH https://api.hoody.icu/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"
    }
  }'

TypeScript SDK

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

Request Body

Field	Type	Required	Description
public_key	string | null	No	ED25519 public key (64 hex chars) or null to clear.
public_storage	object | null	No	Public JSON profile storage (max 64KB) or null to clear.

At least one of public_key or public_storage must be provided.

Response

200

{
  "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 }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:00:00.000Z"
  }
}

400

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

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

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

Delete auth token

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

cURL

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

TypeScript SDK

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

Parameters

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

Response

200

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

400

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

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

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

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