API Tokens

Download Page (.md)

The API tokens endpoints let you mint, inspect, update, copy, and revoke long-lived authentication tokens used for programmatic access and automation. Use them to issue scoped credentials for CI jobs, external integrations, and delegated sub-accounts, with optional IP restrictions, realm scoping, and time-bound expiry.

List auth tokens

Return all auth tokens belonging to the authenticated user. Token values are never included in the response — only metadata, permissions, and usage state.

This endpoint takes no parameters.

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

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

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

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

Retrieve the full metadata of a single auth token by its ID. The token value itself is not returned.

Parameters

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

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

const token = await client.api.authTokens.get("507f1f77bcf86cd799439011");

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

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

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

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

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

This endpoint takes no parameters.

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

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

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

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

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

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

Parameters

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

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

const profile = await client.api.authTokens.getPublicProfile(
  "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234"
);

{
  "statusCode": 200,
  "message": "Auth token public profile retrieved successfully",
  "data": {
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Acme Integrations",
      "tier": "gold"
    }
  }
}

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

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

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

List permission templates

List the permission-template catalog with each template’s resolved permission tree (read-only; no secrets). Used by the token-creation UI to offer delegation without mirroring server templates client-side.

This endpoint takes no parameters.

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

const templates = await client.api.authTokens.listAuthTokenPermissionTemplates();

{}

Create a new auth token

Create a new long-term authentication token with optional IP restrictions, realm scoping, and expiration. The full token value is returned exactly once in the response.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`alias`	string	No	User-friendly alias for the token. If not provided, a random animal name is generated (e.g., `clever-dolphin`).
`public_key`	string \| null	No	Optional ED25519 public key as a 64-character hexadecimal string.
`public_storage`	object \| null	No	Optional public JSON profile storage, max 64KB serialized.
`ip_whitelist`	array \| string	No	IPv4 addresses/CIDR ranges, comma-separated string, or ``. Defaults to ``.
`permission_template`	string	No	Optional template name. Takes precedence over `permissions` if provided. Templates: `full_access`, `external_customer`, `dev_team`, `finance_team`, `read_only`.
`permissions`	object	No	Fine-grained permissions for this token. Missing paths default to false (deny).
`realm_ids`	array	No	List of realm IDs this token is restricted to.
`allow_no_realm`	boolean	No	Whether this token can be used without a realm scope. Defaults to true.
`vault_access`	boolean	No	Whether this token can access user vault endpoints. Defaults to false.
`event_access`	boolean	No	Whether this token can access event streams and history. Defaults to true.
`deny_reauthorization`	boolean	No	Produce a locked-down leaf: strips `create_tokens` and `vault`, forces `vault_access` to false, forces a non-permanent expiry. Rejected with 400 if combined with explicit `create_tokens`/`vault`/`vault_access` grants.
`expires_at`	string \| string \| number	No	ISO 8601 date, Unix timestamp, `today`, or `tomorrow`. Omit for non-expiring.
`otp_code`	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

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
  }'

const created = await client.api.authTokens.create({
  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
});

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

{
  "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
`DUPLICATE_ALIAS`	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

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

Add realm to auth token

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

Parameters

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

Request Body

Name	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.

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": "507f1f77bcf86cd799439033"
  }'

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

{
  "statusCode": 200,
  "message": "Realm added to auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": ["507f1f77bcf86cd799439033"],
    "allow_no_realm": false,
    "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"
  }
}

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

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

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

Copy auth token

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

Parameters

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

Request Body

Name	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 \| string \| number \| null	No	Optional expiration override. If omitted, the source expiration is copied when still in the future.
`otp_code`	string	No	TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT.

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"
  }'

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

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

{
  "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
`DUPLICATE_ALIAS`	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

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

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

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

Remove realm from auth token

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

Parameters

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

Request Body

Name	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.

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": "507f1f77bcf86cd799439033"
  }'

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

{
  "statusCode": 200,
  "message": "Realm removed from auth token 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"
  }
}

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

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

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

Update auth token

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

Parameters

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

Request Body

Name	Type	Required	Description
`alias`	string	No	User-friendly alias for the token.
`public_key`	string \| null	No	ED25519 public key as a 64-character hexadecimal string, or null to clear.
`public_storage`	object \| null	No	Public JSON profile storage (max 64KB), or null to clear.
`ip_whitelist`	array \| string	No	IPv4 addresses/CIDR ranges, comma-separated string, or `*`.
`permissions`	object	No	Fine-grained permissions. Missing paths default to false.
`realm_ids`	array	No	List of realm IDs this token is restricted to.
`allow_no_realm`	boolean	No	Whether this token can be used without a realm scope.
`vault_access`	boolean	No	Whether this token can access user vault endpoints.
`event_access`	boolean	No	Whether this token can access event streams and history.
`expires_at`	string \| 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.

curl -X PUT 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,
    "is_enabled": false
  }'

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

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

{
  "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
`DUPLICATE_ALIAS`	Token alias already exists	You already have an authentication token with this alias	Choose a different unique alias for this token

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

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

Update current auth token public profile

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

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`public_key`	string \| null	No	ED25519 public key as a 64-character hexadecimal string, 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 supplied.

curl -X PUT 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"
    }
  }'

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

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

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

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

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

Permanently delete an auth token. After deletion, 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 -X DELETE https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>"

await client.api.authTokens.delete("507f1f77bcf86cd799439011");

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

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

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

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

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