Realms (API Isolation)

The Realms endpoints let you enumerate the realm identifiers attached to your resources for multi-tenant isolation. A realm is a 24-character hexadecimal string that groups projects, containers, servers (accessed through pools), and auth tokens into a tenant boundary. Use these endpoints when you need to discover which realms your account spans, or when you want to attach usage counters to each realm for inventory or billing reconciliation.

List your realm IDs

Returns the deduplicated set of 24-hex realm identifiers found across your projects, containers, servers (via pool memberships), and auth tokens. The calling token must hold the resources.realms permission.

GET /api/v1/realms/

Parameters

Name	In	Type	Required	Description
`include_usage`	query	boolean	No	Include resource counts per realm_id (`projects`, `containers`, `servers`, `auth_tokens`). When `true`, the response data includes a `usage` object keyed by realm_id. Default: `false`

Request

This endpoint takes no request body.

Response

{
  "statusCode": 200,
  "message": "Realm IDs retrieved successfully",
  "data": {
    "realm_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "total": 2
  }
}

When include_usage=true, each data.realm_ids entry is mirrored in data.usage with its projects, containers, servers, and auth_tokens counts.

{
  "statusCode": 401,
  "error": "UNAUTHORIZED",
  "message": "Authentication required"
}

Error Code	Title	Description	Resolution
`UNAUTHORIZED`	Authentication required	No valid authentication credentials were provided with the request.	Provide a valid JWT or auth token in the `Authorization` header (for example, `Authorization: Bearer <token>`).
`MISSING_TOKEN`	Authentication token missing	No authentication token was sent with 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 use a different valid auth token.
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired.	Obtain a new token by logging in again, or refresh the session.
`AUTH_TOKEN_LINEAGE_REVOKED`	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
`INVALID_CREDENTIALS`	Invalid credentials	The provided username/email or password is incorrect.	Verify the credentials and try again, or use the password reset feature.
`EMAIL_NOT_VERIFIED`	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
`INVALID_OTP_CODE`	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "message": "This token does not have permission: resources.realms"
}

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	Permission denied	The auth token does not carry the `resources.realms` permission required to list realms.	Recreate the token with the `full_access` template, or explicitly set `resources.realms: true` in the token’s permissions.
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	The authenticated principal does not have the permissions required to perform this action.	Ask the resource owner to grant access, or sign in with an account that has the required permission.
`ACCOUNT_BANNED`	Account banned	The account has been banned and cannot access this resource.	Contact support for information about the account status.

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Examples

List realm IDs without usage counts:

curl -X GET 'https://api.hoody.com/api/v1/realms/' \
  -H 'Authorization: Bearer <token>'

List realm IDs with usage counts:

curl -X GET 'https://api.hoody.com/api/v1/realms/?include_usage=true' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

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

// List realm IDs without usage counts
await client.api.realms.list();

// List realm IDs with usage counts
await client.api.realms.list({ include_usage: true });

{
  "statusCode": 200,
  "message": "Realm IDs retrieved successfully",
  "data": {
    "realm_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "total": 2
  }
}

{
  "statusCode": 200,
  "message": "Realm IDs retrieved successfully",
  "data": {
    "realm_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "total": 2,
    "usage": {
      "507f1f77bcf86cd799439011": {
        "projects": 2,
        "containers": 15,
        "servers": 1,
        "auth_tokens": 1
      },
      "507f1f77bcf86cd799439012": {
        "projects": 1,
        "containers": 8,
        "servers": 0,
        "auth_tokens": 0
      }
    }
  }
}