Realms (API Isolation)

The Realms API lets you discover the multi-tenant realms (identified by 24-hexadecimal strings) that your resources belong to. Use these endpoints to audit which realms your projects, containers, servers, and auth tokens are associated with.

This page covers the List Realms endpoint, which returns a deduplicated list of realm identifiers found across your resources. Requires the resources.realms permission.

List Realms

GET /api/v1/realms/

Returns all unique realm_id values found in your projects, containers, servers (via pool memberships), and auth tokens. The response is a deduplicated list of 24-hexadecimal realm identifiers that your resources belong to.

Pass include_usage=true to also receive a per-realm count of projects, containers, servers, and auth tokens.

Parameters

Name	In	Type	Required	Description
include_usage	query	boolean	No	Include resource counts per realm_id (projects, containers, servers, auth_tokens). Adds a usage object to the response data. Default: false

Request

This endpoint accepts no request body.

cURL

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

SDK

const { data } = await client.api.realms.list({ include_usage: true });

Response

200 — Success

200

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

The usage object is only present when include_usage=true is passed in the query string.

401 — Unauthorized

401

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

Error Code	Title	Description	Resolution
UNAUTHORIZED	Authentication required	No valid authentication credentials provided	Provide valid JWT token or auth token in Authorization header

403 — Permission Denied

403

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

Error Code	Title	Description	Resolution
PERMISSION_DENIED	Permission denied	Auth token does not have resources.realms permission	Recreate token with full_access template or explicitly add resources.realms: true to token permissions