Proxy permissions define which requests reach your container’s services and which programs each authenticated identity may use. Use these endpoints to read, replace, mutate, or delete the authentication groups, program access rules, default policy, and proxy enable-state on a project or on a specific container. Every write operation requires the If-Match: file:v precondition header; read the current file_version from GET first (use file:v0 to bootstrap when no document is stored).

The set of supported authentication group types is jwt, password, ip, token, and hoody-identity. Each project/container stores one document containing both the groups and the per-group program permissions.

Container proxy permissions

GET /api/v1/containers/{id}/proxy/permissions

Retrieve the full proxy access control configuration for a single container, including authentication groups, per-group program permissions, default policy, and proxy enable-state.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Response

200

{
  "statusCode": 200,
  "message": "Container proxy permissions retrieved successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "deny",
    "enable_proxy": true,
    "file_version": 3,
    "etag": "file:v3"
  }
}

404

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

SDK usage

cURL

curl https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions

SDK

await client.api.proxyPermissionsContainer.get("507f1f77bcf86cd799439012");

PUT /api/v1/containers/{id}/proxy/permissions

Replace the entire container proxy permissions document. Requires If-Match: file:v (428 when absent, 412 when stale).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
project	string	Yes	Project ID owning this container
container	string	Yes	Container ID (must match path id)
groups	object	Yes	Authentication groups configuration
permissions	object	Yes	Per-group program access rules
default	string (allow | deny)	No	Defaults to deny if omitted
enable_proxy	boolean	No	Enable or disable the proxy. Defaults to true
hooks	object	No	Per-service proxy hook arrays

Response

200

{
  "statusCode": 200,
  "message": "Container proxy permissions updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid proxy permissions configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }'

SDK

await client.api.proxyPermissionsContainer.replace(
  "507f1f77bcf86cd799439012",
  {
    project: "507f1f77bcf86cd799439011",
    container: "507f1f77bcf86cd799439012",
    groups: {},
    permissions: {},
    default: "deny"
  },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/containers/{id}/proxy/permissions

Delete the container proxy permissions document.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Container proxy permissions deleted successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "allow"
  }
}

404

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

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsContainer.delete(
  "507f1f77bcf86cd799439012",
  { ifMatch: "file:v3" }
);

PATCH /api/v1/containers/{id}/proxy/permissions/default

Update only the container default access policy (allow or deny) without touching groups or program permissions.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
default	string (allow | deny)	Yes	Default access policy for unmatched requests

Response

200

{
  "statusCode": 200,
  "message": "Default policy updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "allow"
  }
}

SDK usage

cURL

curl -X PATCH https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/default \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"default": "allow"}'

SDK

await client.api.proxyPermissionsContainer.updateDefault(
  "507f1f77bcf86cd799439012",
  { default: "allow" },
  { ifMatch: "file:v3" }
);

PATCH /api/v1/containers/{id}/proxy/permissions/state

Enable or disable the proxy for a single container.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
enable_proxy	boolean	Yes	Enable or disable the proxy entirely

Response

200

{
  "statusCode": 200,
  "message": "Proxy state updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "deny",
    "enable_proxy": true
  }
}

SDK usage

cURL

curl -X PATCH https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/state \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"enable_proxy": true}'

SDK

await client.api.proxyPermissionsContainer.updateState(
  "507f1f77bcf86cd799439012",
  { enable_proxy: true },
  { ifMatch: "file:v3" }
);

Container authentication groups

Configure named authentication groups for a container. Each group belongs to one of the supported types: jwt, password, ip, token, or hoody-identity.

Note

Group names match ^[A-Za-z0-9_-]{1,50}$. A group can be an OR-array of multiple typed entries to express “any of these checks pass” (for example, allow either an IP-range match or a JWT match).

PUT /api/v1/containers/{id}/proxy/permissions/groups/{groupName}/jwt

Create or replace a JWT authentication group on a container. The JWT is verified against the configured secret/algorithm; required claims must match exactly.

This group verifies JWTs your app issues - not Hoody identity claims

The identity_claim returned by Hoody login is a detached-signature ED25519 bundle, not a JWT, and cannot be validated by a jwt group. If you want to gate your container on a real Hoody identity, use the native hoody-identity group type instead. A jwt group expects the caller to mint its own tokens (HS256/RS256/ES256) using a key the container document holds.

The hoody-identity group config is { audience (REQUIRED), sources? (header-only, X-Hoody-Identity- namespace), allow_types?, users?, max_age_seconds? (≥300), expose_type? } and never carries key material - the operator owns the trust keyring. See Hoody Identity Authentication and Identity Claims.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
secret	string	Yes	JWT secret key used to verify token signatures. For HS256: any string. For RS256/ES256: PEM-encoded SPKI public key.
algorithm	string (HS256 | RS256 | ES256)	Yes	JWT algorithm to use for signature verification.
sources	array	Yes	Where to look for JWT tokens. Format: header:Name or cookie:Name.
claims	object	No	Optional JWT claims that must be present and match exactly. Values must be string, number, or boolean.

Response

200

{
  "statusCode": 200,
  "message": "JWT authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "admin": {
        "type": "jwt"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid JWT configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/groups/admin/jwt \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "secret": "shared-secret-change-me",
    "algorithm": "HS256",
    "sources": ["header:Authorization"],
    "claims": { "role": "admin" }
  }'

SDK

await client.api.proxyPermissionsContainer.setJwtGroup(
  "507f1f77bcf86cd799439012",
  "admin",
  {
    secret: "shared-secret-change-me",
    algorithm: "HS256",
    sources: ["header:Authorization"],
    claims: { role: "admin" }
  },
  { ifMatch: "file:v3" }
);

PUT /api/v1/containers/{id}/proxy/permissions/groups/{groupName}/password

Create or replace a password authentication group on a container. Passwords are stored as SHA256(salt + password) in lowercase hex.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
username	string	Yes	Username for authentication. Must match exactly what the client provides.
password	string	Yes	Password for authentication. Can be plaintext (will be hashed) or pre-hashed SHA256(salt + password) in lowercase hex format.
algorithm	string (sha256)	No	Hashing algorithm used for password verification. Currently only SHA256 is supported.
salt	string	Yes	Salt used for password hashing. Should be unique per user/group for security.

Response

200

{
  "statusCode": 200,
  "message": "Password authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "users": {
        "type": "password"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid password configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/groups/users/password \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "username": "admin",
    "password": "s3cret",
    "salt": "b3e7c4a15d2e",
    "algorithm": "sha256"
  }'

SDK

await client.api.proxyPermissionsContainer.setPasswordGroup(
  "507f1f77bcf86cd799439012",
  "users",
  {
    username: "admin",
    password: "s3cret",
    salt: "b3e7c4a15d2e",
    algorithm: "sha256"
  },
  { ifMatch: "file:v3" }
);

PUT /api/v1/containers/{id}/proxy/permissions/groups/{groupName}/ip

Create or replace an IP-range authentication group on a container. Matches are evaluated against the request’s source IPv4 address.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
range	string	Yes	IPv4 CIDR range specifying allowed IP addresses. Format: IP/mask where mask is 0-32. Examples: 192.168.1.0/24, 10.0.0.0/8, 203.0.113.5/32.

Response

200

{
  "statusCode": 200,
  "message": "IP authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "office": {
        "type": "ip"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid IP CIDR range"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/groups/office/ip \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"range": "192.168.1.0/24"}'

SDK

await client.api.proxyPermissionsContainer.setIpGroup(
  "507f1f77bcf86cd799439012",
  "office",
  { range: "192.168.1.0/24" },
  { ifMatch: "file:v3" }
);

PUT /api/v1/containers/{id}/proxy/permissions/groups/{groupName}/token

Create or replace a static-token authentication group on a container. The token must be supplied in exactly one location: a header, a cookie, or a query parameter.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Supply exactly one of the following shapes:

• Header token - header (string, required) and value (string, required)
• Cookie token - cookie (string, required) and value (string, required)
• Query param token - param (string, required) and value (string, required)

Response

200

{
  "statusCode": 200,
  "message": "Token authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "external-api": {
        "type": "token"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid token configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/groups/external-api/token \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"header": "X-API-Key", "value": "tok_4f12a8"}'

SDK

await client.api.proxyPermissionsContainer.setTokenGroup(
  "507f1f77bcf86cd799439012",
  "external-api",
  { header: "X-API-Key", value: "tok_4f12a8" },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/containers/{id}/proxy/permissions/groups/{groupName}

Remove an authentication group from a container. Program permissions that referenced the group remain in the document but will no longer match any authenticated identity.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name to remove
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Authentication group removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "admin": {
        "type": "jwt"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container or group not found"
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/groups/admin \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsContainer.removeAuthGroup(
  "507f1f77bcf86cd799439012",
  "admin",
  { ifMatch: "file:v3" }
);

Container group program permissions

Per-group program access rules. Each rule defines WHICH instances/ports are ALLOWED, not which exist. Use true to allow all, false to deny all, a port number for a single port, an array of ports, a "8000-8100" range, or "*" as the wildcard.

PUT /api/v1/containers/{id}/proxy/permissions/permissions/{groupName}

Set or replace one program access rule for a container group.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
program	string	Yes	Program name to set the access rule for (e.g., http, terminal, ssh, files, exec, services, notifications).
access	boolean | number | array | string	Yes	Access control rule: true = allow all, false = deny all; a number = allow only that port; an array of numbers = allow only those ports; a "8000-8100" string = allow a port range; "*" = allow all (same as true). For files, services, notifications, exec only boolean is allowed.

Response

200

{
  "statusCode": 200,
  "message": "Group program permission set successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {
      "admin": {
        "http": [80, 443]
      }
    },
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid permission value"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/permissions/admin \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{ "program": "http", "access": [80, 443] }'

SDK

await client.api.proxyPermissionsContainer.setGroup(
  "507f1f77bcf86cd799439012",
  "admin",
  { program: "http", access: [80, 443] },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/containers/{id}/proxy/permissions/permissions/{groupName}

Remove every program permission defined for a container group. The group’s authentication configuration is left untouched.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "All group permissions removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/permissions/admin \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsContainer.removeGroup(
  "507f1f77bcf86cd799439012",
  "admin",
  { ifMatch: "file:v3" }
);

DELETE /api/v1/containers/{id}/proxy/permissions/permissions/{groupName}/{program}

Remove a single program permission from a container group.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
program	path	string	Yes	Program name (e.g., http, ssh, files)
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Program permission removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {},
    "permissions": {
      "admin": {
        "http": [8080]
      }
    },
    "default": "deny"
  }
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/proxy/permissions/permissions/admin/http \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsContainer.removeProgram(
  "507f1f77bcf86cd799439012",
  "admin",
  "http",
  { ifMatch: "file:v3" }
);

Project proxy permissions

Project-level documents apply to every container in the project that does not carry its own container-level proxy document. The set of supported group types is jwt, password, ip, token, and hoody-identity.

GET /api/v1/projects/{id}/proxy/permissions

Retrieve the full proxy access control configuration for a project.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID

Response

200

{
  "statusCode": 200,
  "message": "Project proxy permissions retrieved successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny",
    "enable_proxy": true,
    "file_version": 3,
    "etag": "file:v3"
  }
}

404

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

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The specified project ID does not exist or you do not have access to it	Verify the project ID is correct and that you have permission to access this project

SDK usage

cURL

curl https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions

SDK

await client.api.proxyPermissionsProject.get("507f1f77bcf86cd799439011");

PUT /api/v1/projects/{id}/proxy/permissions

Replace the entire project proxy permissions document. Requires If-Match: file:v (428 when absent, 412 when stale).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
project	string	Yes	Project ID (must match path id)
groups	object	Yes	Authentication groups configuration. Key is group name, value is group config.
permissions	object	Yes	Per-group program permissions. Key is group name, value is a map of program -> access-rule.
default	string (allow | deny)	No	Default access policy when no rules match (defaults to deny if omitted)
enable_proxy	boolean	No	Enable or disable the proxy. Defaults to true.

Response

200

{
  "statusCode": 200,
  "message": "Project proxy permissions updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "admin": {
        "type": "jwt",
        "algorithm": "HS256"
      }
    },
    "permissions": {
      "admin": {
        "terminal": true,
        "files": true
      }
    },
    "default": "deny",
    "enable_proxy": true
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid permissions configuration"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	The proxy permissions configuration contains invalid data or missing required fields	Check that all required fields are present and properly formatted according to the schema
INVALID_JWT_CONFIG	Invalid JWT configuration	JWT authentication group has invalid secret, algorithm, or sources configuration	Ensure JWT secret is valid for the algorithm, sources are properly formatted, and claims are scalar values
INVALID_IP_RANGE	Invalid IP CIDR range	IP authentication group has an invalid IPv4 CIDR notation	Use valid IPv4 CIDR format like 192.168.1.0/24 or 10.0.0.1/32

404

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

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The specified project ID does not exist or you do not have access to it	Verify the project ID is correct and that you have permission to access this project

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny",
    "enable_proxy": true
  }'

SDK

await client.api.proxyPermissionsProject.replace(
  "507f1f77bcf86cd799439011",
  {
    project: "507f1f77bcf86cd799439011",
    groups: {},
    permissions: {},
    default: "deny",
    enable_proxy: true
  },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/projects/{id}/proxy/permissions

Remove all proxy access control from a project, reverting it to open access with default allow.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Project proxy permissions deleted successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "allow",
    "enable_proxy": true
  }
}

404

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

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The specified project ID does not exist or you do not have access to it	Verify the project ID is correct and that you have permission to access this project

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsProject.delete(
  "507f1f77bcf86cd799439011",
  { ifMatch: "file:v3" }
);

PATCH /api/v1/projects/{id}/proxy/permissions/default

Update only the project default access policy. The default is the fallback for requests that match no authentication group.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
default	string (allow | deny)	Yes	Default access policy for unmatched requests

Response

200

{
  "statusCode": 200,
  "message": "Default policy updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid default policy value"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid default policy	The default policy must be either allow or deny	Provide a valid default value: allow or deny

404

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

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The specified project ID does not exist or you do not have access to it	Verify the project ID is correct and that you have permission to access this project

SDK usage

cURL

curl -X PATCH https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/default \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"default": "deny"}'

SDK

await client.api.proxyPermissionsProject.updateDefault(
  "507f1f77bcf86cd799439011",
  { default: "deny" },
  { ifMatch: "file:v3" }
);

PATCH /api/v1/projects/{id}/proxy/permissions/state

Enable or disable the proxy for a project. Disabling is a kill-switch: requests that reach the proxy permission layer are denied with 403, evaluated before authentication groups, permission rules, and the default policy. Containers keep running; only proxy reachability is cut.

Note

The project value applies only to containers that do not set enable_proxy themselves. A container document with enable_proxy: true overrides a disabled project, and saving a container permissions document persists an explicit true. Use the container-level endpoint to disable a specific container reliably.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
enable_proxy	boolean	Yes	Enable or disable the proxy entirely

Response

200

{
  "statusCode": 200,
  "message": "Proxy state updated successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny",
    "enable_proxy": false
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid enable_proxy value"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid enable_proxy value	The enable_proxy field must be a boolean (true or false)	Provide a valid boolean value: true to enable proxy, false to disable

404

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

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The specified project ID does not exist or you do not have access to it	Verify the project ID is correct and that you have permission to access this project

SDK usage

cURL

curl -X PATCH https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/state \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"enable_proxy": false}'

SDK

await client.api.proxyPermissionsProject.updateState(
  "507f1f77bcf86cd799439011",
  { enable_proxy: false },
  { ifMatch: "file:v3" }
);

Project authentication groups

Configure named authentication groups at the project level. Each group belongs to one of: jwt, password, ip, token, or hoody-identity.

Note

Group names match ^[A-Za-z0-9_-]{1,50}$. A group can be an OR-array of multiple typed entries to express “any of these checks pass” (for example, allow either an IP-range match or a JWT match).

PUT /api/v1/projects/{id}/proxy/permissions/groups/{groupName}/jwt

Create or replace a JWT authentication group at the project level.

This group verifies JWTs your app issues - not Hoody identity claims

The identity_claim returned by Hoody login is a detached-signature ED25519 bundle, not a JWT, and cannot be validated by a jwt group. If you want to gate your project on a real Hoody identity, use the native hoody-identity group type instead. A jwt group expects the caller to mint its own tokens (HS256/RS256/ES256) using a key the project document holds.

The hoody-identity group config is { audience (REQUIRED), sources? (header-only, X-Hoody-Identity- namespace), allow_types?, users?, max_age_seconds? (≥300), expose_type? } and never carries key material - the operator owns the trust keyring. See Hoody Identity Authentication and Identity Claims.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
secret	string	Yes	JWT secret key used to verify token signatures. For HS256: any string. For RS256/ES256: PEM-encoded SPKI public key.
algorithm	string (HS256 | RS256 | ES256)	Yes	JWT algorithm to use for signature verification.
sources	array	Yes	Where to look for JWT tokens. Format: header:Name or cookie:Name.
claims	object	No	Optional JWT claims that must be present and match exactly. Values must be string, number, or boolean.

Response

200

{
  "statusCode": 200,
  "message": "JWT authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "admin": {
        "type": "jwt",
        "algorithm": "HS256"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid JWT configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/groups/admin/jwt \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "secret": "shared-secret-change-me",
    "algorithm": "HS256",
    "sources": ["header:Authorization"],
    "claims": { "role": "admin" }
  }'

SDK

await client.api.proxyPermissionsProject.setJwtGroup(
  "507f1f77bcf86cd799439011",
  "admin",
  {
    secret: "shared-secret-change-me",
    algorithm: "HS256",
    sources: ["header:Authorization"],
    claims: { role: "admin" }
  },
  { ifMatch: "file:v3" }
);

PUT /api/v1/projects/{id}/proxy/permissions/groups/{groupName}/password

Create or replace a password authentication group at the project level. Passwords are stored as SHA256(salt + password) in lowercase hex.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
username	string	Yes	Username for authentication. Must match exactly what the client provides.
password	string	Yes	Password for authentication. Can be plaintext (will be hashed) or pre-hashed SHA256(salt + password) in lowercase hex format.
algorithm	string (sha256)	No	Hashing algorithm used for password verification. Currently only SHA256 is supported.
salt	string	Yes	Salt used for password hashing. Should be unique per user/group for security.

Response

200

{
  "statusCode": 200,
  "message": "Password authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "users": {
        "type": "password",
        "username": "admin"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid password configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/groups/users/password \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "username": "admin",
    "password": "s3cret",
    "salt": "b3e7c4a15d2e",
    "algorithm": "sha256"
  }'

SDK

await client.api.proxyPermissionsProject.setPasswordGroup(
  "507f1f77bcf86cd799439011",
  "users",
  {
    username: "admin",
    password: "s3cret",
    salt: "b3e7c4a15d2e",
    algorithm: "sha256"
  },
  { ifMatch: "file:v3" }
);

PUT /api/v1/projects/{id}/proxy/permissions/groups/{groupName}/ip

Create or replace an IP-range authentication group at the project level.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
range	string	Yes	IPv4 CIDR range specifying allowed IP addresses. Format: IP/mask where mask is 0-32. Examples: 192.168.1.0/24, 10.0.0.0/8, 203.0.113.5/32.

Response

200

{
  "statusCode": 200,
  "message": "IP authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "office": {
        "type": "ip",
        "range": "192.168.1.0/24"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid IP CIDR range"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/groups/office/ip \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"range": "192.168.1.0/24"}'

SDK

await client.api.proxyPermissionsProject.setIpGroup(
  "507f1f77bcf86cd799439011",
  "office",
  { range: "192.168.1.0/24" },
  { ifMatch: "file:v3" }
);

PUT /api/v1/projects/{id}/proxy/permissions/groups/{groupName}/token

Create or replace a static-token authentication group at the project level. Supply exactly one location: header, cookie, or param.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Supply exactly one of the following shapes:

• Header token - header (string, required) and value (string, required)
• Cookie token - cookie (string, required) and value (string, required)
• Query param token - param (string, required) and value (string, required)

Response

200

{
  "statusCode": 200,
  "message": "Token authentication group configured successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "api-clients": {
        "type": "token",
        "header": "X-API-Key"
      }
    },
    "permissions": {},
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid token configuration"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/groups/api-clients/token \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"header": "X-API-Key", "value": "tok_4f12a8"}'

SDK

await client.api.proxyPermissionsProject.setTokenGroup(
  "507f1f77bcf86cd799439011",
  "api-clients",
  { header: "X-API-Key", value: "tok_4f12a8" },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/projects/{id}/proxy/permissions/groups/{groupName}

Remove an authentication group from a project. Program permissions referencing the group remain in the document but will no longer match any authenticated identity.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name to remove
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Authentication group removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project or group not found"
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/groups/admin \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsProject.removeAuthGroup(
  "507f1f77bcf86cd799439011",
  "admin",
  { ifMatch: "file:v3" }
);

Project group program permissions

Per-group program access rules at the project level. Each rule defines WHICH instances/ports are ALLOWED, not which exist.

PUT /api/v1/projects/{id}/proxy/permissions/permissions/{groupName}

Set or replace one program access rule for a project group.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Request Body

Field	Type	Required	Description
program	string	Yes	Program name to set the access rule for (e.g., http, terminal, ssh, files, exec, services, notifications).
access	boolean | number | array | string	Yes	Access control rule: true = allow all, false = deny all; a number = allow only that port; an array of numbers = allow only those ports; a "8000-8100" string = allow a port range; "*" = allow all (same as true). For files, services, notifications, exec only boolean is allowed.

Response

200

{
  "statusCode": 200,
  "message": "Group program permission set successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {
      "admin": {
        "http": [8080]
      }
    },
    "default": "deny"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid permission value"
}

SDK usage

cURL

curl -X PUT https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/permissions/admin \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{ "program": "http", "access": [8080] }'

SDK

await client.api.proxyPermissionsProject.setGroup(
  "507f1f77bcf86cd799439011",
  "admin",
  { program: "http", access: [8080] },
  { ifMatch: "file:v3" }
);

DELETE /api/v1/projects/{id}/proxy/permissions/permissions/{groupName}

Remove every program permission defined for a project group. The group’s authentication configuration is left untouched.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "All group permissions removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {},
    "default": "deny"
  }
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/permissions/admin \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsProject.removeGroup(
  "507f1f77bcf86cd799439011",
  "admin",
  { ifMatch: "file:v3" }
);

DELETE /api/v1/projects/{id}/proxy/permissions/permissions/{groupName}/{program}

Remove a single program permission from a project group.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
program	path	string	Yes	Program name (e.g., http, ssh, files)
if-match	header	string	No	file:v ETag precondition - read current file_version from GET first

Response

200

{
  "statusCode": 200,
  "message": "Program permission removed successfully",
  "data": {
    "project": "507f1f77bcf86cd799439011",
    "groups": {},
    "permissions": {
      "admin": {
        "http": [8080]
      }
    },
    "default": "deny"
  }
}

SDK usage

cURL

curl -X DELETE https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/proxy/permissions/permissions/admin/http \
  -H "If-Match: file:v3"

SDK

await client.api.proxyPermissionsProject.removeProgram(
  "507f1f77bcf86cd799439011",
  "admin",
  "http",
  { ifMatch: "file:v3" }
);