Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

API Tokens

Section titled “API Tokens”

API tokens are long-lived bearer credentials for programmatic access to Hoody. They support fine-grained permissions, IP whitelisting, realm scoping, optional expiration, and delegated issuance (child tokens clamped to a subset of the parent’s permissions). Use these endpoints to mint, inspect, edit, copy, and revoke tokens belonging to your account.

The token secret is only returned once, on create or copy. After that, only metadata is exposed via the read endpoints.

Listing and introspection

Section titled “Listing and introspection”

GET /api/v1/auth/tokens

Section titled “GET /api/v1/auth/tokens”

List all auth tokens owned by the authenticated account. Token secret values are never included; only metadata, permissions, and usage telemetry are returned. The truncated flag, when present, indicates that a delegated-token subtree listing was capped at the fanout limit and the returned list is incomplete.

This endpoint takes no parameters.

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

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

Section titled “GET /api/v1/auth/tokens/{id}”

Fetch a single auth token by its 24-character hex ID. The response mirrors the list entry shape but scoped to one token; the secret value is never included.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the token
Terminal window
curl -X GET "https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"

GET /api/v1/auth/tokens/me

Section titled “GET /api/v1/auth/tokens/me”

Return metadata, permissions, and realm restrictions for the currently authenticated auth token. This endpoint is intentionally reachable on the base control plane (api.hoody.com) so that realm-scoped tokens can bootstrap realm discovery.

This endpoint takes no parameters.

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

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

Section titled “GET /api/v1/auth/tokens/public-profiles/{public_key}”

Resolve an ED25519 public key to its associated auth token public profile storage object. This is the read side of the public-key/profile mechanism used to publish identifying metadata for a token without exposing its secret.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
public_keypathstringYesED25519 public key to resolve
Terminal window
curl -X GET "https://api.hoody.com/api/v1/auth/tokens/public-profiles/a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234" \
  -H "Authorization: Bearer <token>"

GET /api/v1/auth/tokens/templates

Section titled “GET /api/v1/auth/tokens/templates”

List the server-side permission-template catalog. Each entry contains the template name, description, and its resolved permission tree. Read-only; no secrets are returned. The token-creation UI consumes this endpoint to offer delegation options without mirroring the templates client-side.

This endpoint takes no parameters.

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

Creation and modification

Section titled “Creation and modification”

POST /api/v1/auth/tokens

Section titled “POST /api/v1/auth/tokens”

Mint a new long-lived auth token. Returns the secret exactly once in the response body; store it immediately, as it cannot be retrieved later.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
aliasstringNoUser-friendly alias. If omitted, a random animal name is generated (e.g., clever-dolphin)
public_keystring | nullNoED25519 public key as 64-character hex string, or null to clear
public_storageobject | nullNoArbitrary public JSON profile (max 64KB serialized), or null to clear
ip_whitelistarray | stringNoIPv4 addresses/CIDR ranges, a comma-separated string, or *. Defaults to *
permission_templatestringNoOne of: full_access, external_customer, dev_team, finance_team, read_only. Takes precedence over permissions when provided
permissionsobjectNoFine-grained permission tree. Missing paths default to false (deny)
realm_idsarrayNoRealm IDs the token is restricted to. Token can ONLY be used on these realm subdomains
allow_no_realmbooleanNoWhether the token may be used without a realm scope. Defaults to true. Set to false for strict sub-account tokens
vault_accessbooleanNoWhether the token can access user vault endpoints. Defaults to false
event_accessbooleanNoWhether the token can access real-time event streams and history. Defaults to true
deny_reauthorizationbooleanNoOpt-in least-privilege belt. Strips resources.create_tokens and resources.vault, forces vault_access to false, and requires a bounded expiry. Rejected (400) if combined with explicit grants of those leaves
expires_atstring | string | numberNoISO 8601 timestamp, Unix timestamp (seconds/ms), today, or tomorrow. Omit for non-expiring
otp_codestringNoTOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT
Terminal window
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
  }'

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

Section titled “POST /api/v1/auth/tokens/{id}/copy”

Duplicate an existing token’s configuration (permissions, realm restrictions, IP whitelist) into a new token with a freshly generated secret. The new token’s secret is returned exactly once.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the token

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
aliasstringNoAlias for the copied token. If omitted, a deterministic name like <source> copy is generated
expires_atstring | string | number | nullNoExpiration override. If omitted, source expiration is copied when still in the future. Set to null to make the copy non-expiring
otp_codestringNoTOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT
Terminal window
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"
  }'

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

Section titled “PUT /api/v1/auth/tokens/{id}”

Update an existing token’s mutable fields: alias, public key/profile storage, IP whitelist, permissions, realm restrictions, vault/event access, expiration, and enabled status. The secret value cannot be rotated through this endpoint; use copy to mint a new secret that inherits the same configuration.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the token to update

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
aliasstringNoUser-friendly alias for the token
public_keystring | nullNoED25519 public key (64 hex chars), or null to clear
public_storageobject | nullNoArbitrary public JSON profile (max 64KB), or null to clear
ip_whitelistarray | stringNoIPv4 addresses/CIDR ranges, comma-separated string, or *
permissionsobjectNoFine-grained permission tree. Missing paths default to false (deny)
realm_idsarrayNoList of realm IDs this token is restricted to
allow_no_realmbooleanNoWhether this token can be used without a realm scope
vault_accessbooleanNoWhether this token can access user vault endpoints
event_accessbooleanNoWhether this token can access real-time event streams and history
expires_atstring | string | number | nullNoISO 8601 string, Unix timestamp, today, tomorrow, or null for non-expiring
is_enabledbooleanNoEnable or disable the token
otp_codestringNoTOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT
Terminal window
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",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Updated Profile",
      "links": {
        "website": "https://example.com"
      }
    },
    "ip_whitelist": ["*"],
    "vault_access": false,
    "expires_at": null,
    "is_enabled": false
  }'

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

Section titled “PUT /api/v1/auth/tokens/me/public-profile”

Update the public key and public-storage payload attached to the currently authenticated token. Requires the resources.auth_token_public_profile permission on the token itself. The endpoint targets /me — the token acting on its own profile, not a sibling token.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
public_keystring | nullNoED25519 public key (64 hex chars), or null to clear
public_storageobject | nullNoArbitrary public JSON profile (max 64KB), or null to clear
Terminal window
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"
    }
  }'

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

Section titled “POST /api/v1/auth/tokens/{id}/add-realm”

Atomically add a realm ID to an auth token’s allowlist. The operation is idempotent: if the realm is already present, the endpoint returns success without modification.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesAuth token ID

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
realm_idstringYesRealm ID to add to the token
otp_codestringNoTOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled
Terminal window
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"
  }'

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

Section titled “POST /api/v1/auth/tokens/{id}/remove-realm”

Atomically remove a realm ID from an auth token’s allowlist. The operation is idempotent: if the realm is not present, the endpoint returns success without modification.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesAuth token ID

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
realm_idstringYesRealm ID to remove from the token
otp_codestringNoTOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled
Terminal window
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"
  }'

Deletion

Section titled “Deletion”

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

Section titled “DELETE /api/v1/auth/tokens/{id}”

Permanently delete an auth token. Once deleted, the token cannot be used for authentication and cannot be recovered.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the token
Terminal window
curl -X DELETE "https://api.hoody.com/api/v1/auth/tokens/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"