API Tokens

API tokens provide long-lived credentials for authenticating to the Hoody control plane from scripts, CI/CD pipelines, and external integrations. Each token carries fine-grained permissions, optional IP restrictions, optional realm scoping, and an optional expiration. Tokens support delegation—child tokens inherit a subset of the parent’s permissions and can be revoked independently.

Use the endpoints below to list, create, inspect, update, copy, and revoke tokens, and to manage their realm associations and public profile metadata.

List & Introspect Tokens

`GET /api/v1/auth/tokens`

List all auth tokens for the authenticated user. Token secret values are not included. The result may include tokens in the caller’s delegation subtree; if that fanout is capped, the top-level truncated flag is set to true.

This endpoint takes no parameters.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "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 for a specific auth token by its 24-character hex ID. Token secret value is not included.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_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 /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 host so realm-scoped tokens can bootstrap realm discovery.

This endpoint takes no parameters.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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 /api/v1/auth/tokens/public-profiles/{public_key}`

Resolve and retrieve an auth token’s public profile storage by its ED25519 public key. The public key must be exactly 64 hexadecimal characters.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.authTokens.getPublicProfile('a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234');

{
  "statusCode": 200,
  "message": "Public profile retrieved successfully",
  "data": {
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Production 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

Permission Templates

`GET /api/v1/auth/tokens/templates`

List the permission-template catalog with each template’s resolved permission tree. This is read-only, contains no secrets, and is used by token-creation UIs to offer delegation without mirroring server templates client-side.

This endpoint takes no parameters.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.authTokens.listAuthTokenPermissionTemplates();

{
  "statusCode": 200,
  "message": "Permission templates retrieved successfully",
  "data": []
}

Create, Update & Copy Tokens

`POST /api/v1/auth/tokens`

Create a new long-term auth token with optional IP restrictions, expiration, and fine-grained permissions. The full token secret is returned only in this response—store it immediately.

If 2FA is enabled on the account and you are authenticating with a JWT (rather than another auth token), include otp_code in the body.

This endpoint takes no parameters.

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 as a 64-character hexadecimal string. Set to `null` to clear.
`public_storage`	object \| null	No	Arbitrary public JSON profile (max 64KB serialized). Set to `null` to clear.
`ip_whitelist`	array \| string	No	IPv4 addresses or CIDR ranges, a comma-separated string, or `` to allow all. Defaults to ``.
`permission_template`	string	No	Predefined template name. Takes precedence over `permissions`. One of: `full_access`, `external_customer`, `dev_team`, `finance_team`, `read_only`.
`permissions`	object	No	Fine-grained permission tree. Any missing path defaults to deny.
`realm_ids`	array	No	24-character hex realm IDs this token is restricted to.
`allow_no_realm`	boolean	No	Whether the token may be used on the base host. Defaults to `true`. Set to `false` for strict sub-account tokens.
`vault_access`	boolean	No	Whether the token can access user vault endpoints. Defaults to `false`.
`event_access`	boolean	No	Whether the token can access event streams and history. Defaults to `true`.
`deny_reauthorization`	boolean	No	Opt-in least-privilege belt. Strips `create_tokens`/`vault` permission leaves, forces `vault_access=false`, and forces a bounded expiry. Rejected with 400 if combined with explicit grants.
`expires_at`	string \| number	No	ISO 8601 string, Unix timestamp, `"today"`, `"tomorrow"`, or omit for non-expiring.
`otp_code`	string	No	TOTP (6 digits) or backup code (10 alphanumeric). Required if account has 2FA enabled and you are authenticating via JWT.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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 or CIDR ranges, 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
`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, `"today"`, `"tomorrow"`, or `null`
`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

`PUT /api/v1/auth/tokens/{id}`

Update an existing auth token. You may change the alias, public key/profile storage, IP restrictions, expiration, enabled status, and permissions.

If 2FA is enabled on the account and you are authenticating with a JWT (rather than another auth token), include otp_code in the body.

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 alias. Allowed characters: letters, numbers, spaces, underscores, hyphens.
`public_key`	string \| null	No	New ED25519 public key (64 hex chars), or `null` to clear.
`public_storage`	object \| null	No	New public JSON profile (max 64KB), or `null` to clear.
`ip_whitelist`	array \| string	No	IPv4 addresses or CIDR ranges, comma-separated string, or `*`.
`permissions`	object	No	Replacement permission tree. Missing paths default to deny.
`realm_ids`	array	No	Replacement list of 24-character hex realm IDs.
`allow_no_realm`	boolean	No	Whether the token may be used on the base host.
`vault_access`	boolean	No	Whether the token can access user vault endpoints.
`event_access`	boolean	No	Whether the token can access event streams and history.
`expires_at`	string \| number \| null	No	ISO 8601 string, Unix timestamp, `"today"`, `"tomorrow"`, or `null`.
`is_enabled`	boolean	No	Enable or disable the token.
`otp_code`	string	No	TOTP or backup code. Required if account has 2FA enabled and you are authenticating via JWT.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.authTokens.update('507f1f77bcf86cd799439011', {
  alias: 'Updated Production Key',
  ip_whitelist: ['*'],
  vault_access: false,
  expires_at: null,
  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 or CIDR ranges, 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
`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, `"today"`, `"tomorrow"`, or `null`
`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

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

Copy an existing auth token’s configuration—permissions, realm restrictions, IP whitelist—into a new token with a fresh secret value. Optionally override the alias and expiration on the copy.

If 2FA is enabled on the account and you are authenticating with a JWT (rather than another auth token), include otp_code in the body.

Parameters

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

Request Body

Field	Type	Required	Description
`alias`	string	No	Alias for the copied token. If omitted, a deterministic `<source> copy` alias is generated.
`expires_at`	string \| number \| null	No	Expiration override. If omitted, the source expiration is copied when still in the future.
`otp_code`	string	No	TOTP or backup code. Required if account has 2FA enabled and you are authenticating via JWT.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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, `"today"`, `"tomorrow"`, or `null`
`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

Manage Token Public Profile

`PUT /api/v1/auth/tokens/me/public-profile`

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

This endpoint takes no 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 JSON profile (max 64KB), or `null` to clear.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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-20T11:15: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

Manage Realm Associations

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

Atomically add a realm ID to an auth token’s realm_ids. Idempotent: if the realm is already present, the call succeeds without modification.

If 2FA is enabled on the account and you are authenticating with a JWT (rather than another auth token), include otp_code in the body.

Parameters

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

Request Body

Field	Type	Required	Description
`realm_id`	string	Yes	24-character hex realm ID to add to the token.
`otp_code`	string	No	TOTP or backup code. Required if account has 2FA enabled and you are authenticating via JWT.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.authTokens.addRealm('507f1f77bcf86cd799439011', {
  realm_id: '507f1f77bcf86cd799439012'
});

{
  "statusCode": 200,
  "message": "Realm added to auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Project X Sub-Account",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"],
    "allow_no_realm": false,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T11:15:00.000Z"
  }
}

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

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

{
  "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’s realm_ids. Idempotent: if the realm is not present, the call succeeds without modification.

If 2FA is enabled on the account and you are authenticating with a JWT (rather than another auth token), include otp_code in the body.

Parameters

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

Request Body

Field	Type	Required	Description
`realm_id`	string	Yes	24-character hex realm ID to remove from the token.
`otp_code`	string	No	TOTP or backup code. Required if account has 2FA enabled and you are authenticating via JWT.

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.authTokens.removeRealm('507f1f77bcf86cd799439011', {
  realm_id: '507f1f77bcf86cd799439012'
});

{
  "statusCode": 200,
  "message": "Realm removed from auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Project X Sub-Account",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439011"],
    "allow_no_realm": false,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T11:30:00.000Z"
  }
}

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

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

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

Delete Tokens

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

Permanently delete an auth token. Once deleted, the token can no longer be used for authentication. This action cannot be undone—mint a new token if you need to restore access.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_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