Proxy Permissions

Configure authentication groups and program access rules for proxy endpoints. This page covers both project-level and container-level permissions documents, including reading, replacing, and incrementally updating groups, default policy, and the proxy enable flag. Each document is versioned: read the current file_version via GET, then pass it back as If-Match: file:v<N> on writes.

The supported group types are jwt, password, ip, token, and hoody-identity. The hoody-identity type authenticates against the identity claim returned by Hoody login and never carries operator-owned key material; use it instead of jwt whenever you need to gate a proxy on a logged-in Hoody user.

Note

The project value of enable_proxy 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.

Project proxy permissions

Get project proxy permissions

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

Retrieve the full proxy access control configuration for a project, including authentication groups, program permissions, and the default policy.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID

cURL

curl -X GET https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.get('507f1f77bcf86cd799439011');

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

422

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

Replace project proxy permissions

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

PATCH is also accepted on this endpoint with identical behaviour.

Replace the entire proxy permissions configuration for a project with a new configuration. This operation sets authentication groups, program access rules, default policy, and proxy enable state.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	Type	Required	Description
project	string	Yes	Project ID. Must match path id.
groups	object	Yes	Authentication groups. Key is group name (^[A-Za-z0-9_-]{1,50}$), value is group config. Supported types: jwt, password, ip, token, hoody-identity.
permissions	object	Yes	Per-group program permissions. Key is group name, value is map of program to access rule.
default	string	No	Default access policy when no rules match. Allowed values: allow, deny. Defaults to deny.
enable_proxy	boolean	No	Enable or disable the proxy. Defaults to true.

cURL

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "groups": {
      "admin": {
        "type": "jwt",
        "algorithm": "HS256",
        "secret": "replace-with-strong-secret",
        "sources": ["header:Authorization"]
      }
    },
    "permissions": {
      "admin": {
        "terminal": true,
        "files": true
      }
    },
    "default": "deny",
    "enable_proxy": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.set('507f1f77bcf86cd799439011', {
  project: '507f1f77bcf86cd799439011',
  groups: {
    admin: {
      type: 'jwt',
      algorithm: 'HS256',
      secret: 'replace-with-strong-secret',
      sources: ['header:Authorization']
    }
  },
  permissions: {
    admin: {
      terminal: true,
      files: true
    }
  },
  default: 'deny',
  enable_proxy: true
}, { ifMatch: 'file:v3' });

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

422

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

Update project default policy

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

Update the default access policy (allow or deny) that applies when a request does not match any authentication group rules.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	Type	Required	Description
default	string	Yes	Default access policy for unmatched requests. Allowed values: allow, deny.

cURL

curl -X PATCH https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/default \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"default": "deny"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.setDefault('507f1f77bcf86cd799439011', {
  default: 'deny'
}, { ifMatch: 'file:v3' });

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

422

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

Update project proxy enable state

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

Enable or disable the proxy for a project. Disabling is a kill-switch, not a bypass: while enable_proxy is false, new requests that reach the proxy permission layer are denied with 403, evaluated before authentication groups, permission rules, and the default policy, so no configured rule can re-open access while it is off. Containers keep running; only proxy reachability is cut.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

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

The SDK has one method per value. Each pins enable_proxy itself, so pass an empty data object:

• client.api.proxy.projectPermissions.enable(id, {}, { ifMatch }) sets enable_proxy to true.
• client.api.proxy.projectPermissions.disable(id, {}, { ifMatch }) sets enable_proxy to false.

cURL

curl -X PATCH https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/state \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"enable_proxy": false}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.disable('507f1f77bcf86cd799439011', {}, { ifMatch: 'file:v3' });

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

422

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

Set project IP authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure an ip authentication group that allows requests from a specific IPv4 CIDR range.

Parameters

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

Request Body

Name	Type	Required	Description
range	string	Yes	IPv4 CIDR range. Examples: 192.168.1.0/24, 10.0.0.0/8, 203.0.113.5/32.

cURL

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/office/ip \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"range": "192.168.1.0/24"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

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

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

422

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

Set project JWT authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a jwt authentication group that verifies tokens issued by your application using a configured secret or public key.

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

The jwt group validates standard JWTs signed by a secret you control. The identity bundle returned by Hoody login is not a JWT: it is a detached-signature ED25519 claim that a jwt group cannot validate. To gate a proxy on a logged-in Hoody user, use the hoody-identity group type instead (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	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	Type	Required	Description
secret	string	Yes	JWT secret key. For HS256: any string. For RS256/ES256: PEM-encoded SPKI public key.
algorithm	string	Yes	JWT algorithm. Allowed values: HS256, RS256, ES256.
sources	array	Yes	Where to look for JWT tokens. Format: header:Name or cookie:Name.
claims	object	No	Required JWT claims that must match exactly. Values must be string, number, or boolean.

cURL

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/admin/jwt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "secret": "replace-with-strong-shared-secret",
    "algorithm": "HS256",
    "sources": ["header:Authorization"],
    "claims": {"role": "admin"}
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.setJwtGroup('507f1f77bcf86cd799439011', 'admin', {
  secret: 'replace-with-strong-shared-secret',
  algorithm: 'HS256',
  sources: ['header:Authorization'],
  claims: { role: 'admin' }
}, { ifMatch: 'file:v3' });

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

422

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

Set project password authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a password authentication group that authenticates HTTP Basic requests with a SHA256-hashed credential.

Parameters

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

Request Body

Name	Type	Required	Description
username	string	Yes	Username for authentication. Must match exactly what the client provides.
password	string	Yes	Password for authentication. Plaintext or pre-hashed SHA256(salt+password) in lowercase hex.
salt	string	Yes	Salt used for password hashing. Should be unique per user/group for security.
algorithm	string	No	Hashing algorithm. Allowed values: sha256.

cURL

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/users/password \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "username": "admin",
    "password": "s3cret-password",
    "salt": "8f1c2a3b4d5e6f70",
    "algorithm": "sha256"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.setPasswordGroup('507f1f77bcf86cd799439011', 'users', {
  username: 'admin',
  password: 's3cret-password',
  salt: '8f1c2a3b4d5e6f70',
  algorithm: 'sha256'
}, { ifMatch: 'file:v3' });

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

422

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

Set project token authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a token authentication group that authenticates by exact-match of a single value in a header, cookie, or query parameter. The body shape varies by variant: pick exactly one of header, cookie, or param, and always supply value.

Parameters

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

Request Body

Name	Type	Required	Description
header	string	Yes (in the header variant)	HTTP header name to check for the token (case-insensitive).
cookie	string	Yes (in the cookie variant)	Cookie name to check for the token (case-sensitive).
param	string	Yes (in the param variant)	Query parameter name to check for the token (case-sensitive).
value	string	Yes (in all variants)	Expected token value that must match exactly.

cURL (header)

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/api-clients/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"header": "X-API-Key", "value": "shared-secret-token"}'

cURL (cookie)

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/portal/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"cookie": "session", "value": "shared-secret-token"}'

cURL (param)

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/legacy/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"param": "api_key", "value": "shared-secret-token"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.setTokenGroup('507f1f77bcf86cd799439011', 'api-clients', {
  header: 'X-API-Key',
  value: 'shared-secret-token'
}, { ifMatch: 'file:v3' });

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

422

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

Set project group program permission

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

PATCH is also accepted on this endpoint with identical behaviour.

Set or replace the access rule for a single program within a group. The access value is a rule defining which instances or ports are allowed, not a list of what exists.

Parameters

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

Request Body

Name	Type	Required	Description
program	string	Yes	Program name (for example http, terminal, ssh, files, exec, services, notifications).
access	boolean | number | array | string	Yes	Access rule. Use true/false for boolean, a number for a single port/index, an array of numbers for multiple ports, "8000-8100" for a range, or "*" as a wildcard. For programs files, services, notifications, and exec, only boolean is allowed.

cURL

curl -X PUT https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/permissions/admin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"program": "http", "access": [8080, 8443]}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.setGroupPermission('507f1f77bcf86cd799439011', 'admin', {
  program: 'http',
  access: [8080, 8443]
}, { ifMatch: 'file:v3' });

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

422

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

Delete project proxy permissions

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

Remove all proxy access control configuration from a project, reverting it to open access with default allow policy. This clears all authentication groups and permission rules.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.delete('507f1f77bcf86cd799439011', { ifMatch: 'file:v3' });

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

422

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

Remove project authentication group

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

Delete a single authentication group from the project permissions document.

Parameters

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

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/groups/admin \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.deleteAuthGroup('507f1f77bcf86cd799439011', 'admin', { ifMatch: 'file:v3' });

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

422

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

Remove all permissions for a project group

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

Remove every program-level access rule for a group, while keeping the group itself and its authentication definition intact.

Parameters

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

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/permissions/admin \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.clearGroupPermissions('507f1f77bcf86cd799439011', 'admin', { ifMatch: 'file:v3' });

200

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

422

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

Remove a single program permission for a project group

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

Remove a single program-level access rule from a group, leaving the rest of the group’s permissions untouched.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
groupName	path	string	Yes	Group name
program	path	string	Yes	Program name (for example http, ssh, files)
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/projects/{projectId}/proxy/permissions/permissions/admin/http \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.projectPermissions.deleteGroupPermission('507f1f77bcf86cd799439011', 'admin', 'http', { ifMatch: 'file:v3' });

200

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

422

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

Container proxy permissions

Container-level permissions follow the same shape as project-level permissions but apply to a single container. Container documents also support per-service hooks for request-time evaluation. Use the container endpoints when you need to override a project setting for a single container, since saving a container document persists an explicit enable_proxy value.

Get container proxy permissions

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

Retrieve the full proxy access control configuration for a container, including authentication groups, program permissions, default policy, and per-service hooks.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

cURL

curl -X GET https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.get('507f1f77bcf86cd799439012');

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

422

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

Replace container proxy permissions

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

PATCH is also accepted on this endpoint with identical behaviour.

Replace the entire container proxy permissions configuration, including groups, permissions, default policy, enable_proxy, and per-service hooks. Requires If-Match: file:v<N> header (428 when absent, 412 when stale): read the current file_version via GET first.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	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. Supported types: jwt, password, ip, token, hoody-identity.
permissions	object	Yes	Per-group program permissions. Key is group name, value is map of program to access rule.
default	string	No	Default access policy when no rules match. Allowed values: allow, deny. Defaults to deny.
enable_proxy	boolean	No	Enable or disable the proxy. Defaults to true.
hooks	object	No	Per-service proxy hooks. Keys are service names; values are first-match-wins arrays of { match, script, timeout? } rules. Max 8 per service, 32 per container in total. Reserved services (such as logs, egress and cdp) are rejected.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "admin": {
        "type": "hoody-identity",
        "audience": "https://app.example.com/proxy"
      }
    },
    "permissions": {
      "admin": {
        "terminal": true,
        "files": true
      }
    },
    "default": "deny",
    "enable_proxy": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.set('507f1f77bcf86cd799439012', {
  project: '507f1f77bcf86cd799439011',
  container: '507f1f77bcf86cd799439012',
  groups: {
    admin: {
      type: 'hoody-identity',
      audience: 'https://app.example.com/proxy'
    }
  },
  permissions: {
    admin: {
      terminal: true,
      files: true
    }
  },
  default: 'deny',
  enable_proxy: true
}, { ifMatch: 'file:v3' });

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

422

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

Update container default policy

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

Update the default access policy (allow or deny) for the container.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	Type	Required	Description
default	string	Yes	Default access policy for unmatched requests. Allowed values: allow, deny.

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/default \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"default": "allow"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.setDefault('507f1f77bcf86cd799439012', {
  default: 'allow'
}, { ifMatch: 'file:v3' });

200

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

422

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

Update container proxy enable state

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

Enable or disable the proxy for a container. Saving the container permissions document persists an explicit enable_proxy value, which always overrides the project-level setting.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

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

The SDK has one method per value. Each pins enable_proxy itself, so pass an empty data object:

• client.api.proxy.containerPermissions.enable(id, {}, { ifMatch }) sets enable_proxy to true.
• client.api.proxy.containerPermissions.disable(id, {}, { ifMatch }) sets enable_proxy to false.

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/state \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"enable_proxy": true}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.enable('507f1f77bcf86cd799439012', {}, { ifMatch: 'file:v3' });

200

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

422

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

Set container IP authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure an ip authentication group on a container.

Parameters

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

Request Body

Name	Type	Required	Description
range	string	Yes	IPv4 CIDR range. Examples: 192.168.1.0/24, 10.0.0.0/8, 203.0.113.5/32.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/office/ip \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"range": "192.168.1.0/24"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

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

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

422

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

Set container JWT authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a jwt authentication group on a container that verifies tokens issued by your application.

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

The jwt group validates standard JWTs signed by a secret you control. The identity bundle returned by Hoody login is not a JWT: it is a detached-signature ED25519 claim that a jwt group cannot validate. To gate a proxy on a logged-in Hoody user, use the hoody-identity group type instead (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	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

Request Body

Name	Type	Required	Description
secret	string	Yes	JWT secret key. For HS256: any string. For RS256/ES256: PEM-encoded SPKI public key.
algorithm	string	Yes	JWT algorithm. Allowed values: HS256, RS256, ES256.
sources	array	Yes	Where to look for JWT tokens. Format: header:Name or cookie:Name.
claims	object	No	Required JWT claims that must match exactly. Values must be string, number, or boolean.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/admin/jwt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "secret": "replace-with-strong-shared-secret",
    "algorithm": "HS256",
    "sources": ["header:Authorization"],
    "claims": {"role": "admin"}
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.setJwtGroup('507f1f77bcf86cd799439012', 'admin', {
  secret: 'replace-with-strong-shared-secret',
  algorithm: 'HS256',
  sources: ['header:Authorization'],
  claims: { role: 'admin' }
}, { ifMatch: 'file:v3' });

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

422

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

Set container password authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a password authentication group on a container.

Parameters

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

Request Body

Name	Type	Required	Description
username	string	Yes	Username for authentication. Must match exactly what the client provides.
password	string	Yes	Password for authentication. Plaintext or pre-hashed SHA256(salt+password) in lowercase hex.
salt	string	Yes	Salt used for password hashing. Should be unique per user/group for security.
algorithm	string	No	Hashing algorithm. Allowed values: sha256.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/users/password \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "username": "admin",
    "password": "s3cret-password",
    "salt": "8f1c2a3b4d5e6f70",
    "algorithm": "sha256"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.setPasswordGroup('507f1f77bcf86cd799439012', 'users', {
  username: 'admin',
  password: 's3cret-password',
  salt: '8f1c2a3b4d5e6f70',
  algorithm: 'sha256'
}, { ifMatch: 'file:v3' });

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

422

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

Set container token authentication group

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

PATCH is also accepted on this endpoint with identical behaviour.

Configure a token authentication group on a container. The body shape varies by variant: pick exactly one of header, cookie, or param, and always supply value.

Parameters

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

Request Body

Name	Type	Required	Description
header	string	Yes (in the header variant)	HTTP header name to check for the token (case-insensitive).
cookie	string	Yes (in the cookie variant)	Cookie name to check for the token (case-sensitive).
param	string	Yes (in the param variant)	Query parameter name to check for the token (case-sensitive).
value	string	Yes (in all variants)	Expected token value that must match exactly.

cURL (header)

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/external-api/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"header": "X-API-Key", "value": "shared-secret-token"}'

cURL (cookie)

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/portal/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"cookie": "session", "value": "shared-secret-token"}'

cURL (param)

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/legacy/token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"param": "api_key", "value": "shared-secret-token"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.setTokenGroup('507f1f77bcf86cd799439012', 'external-api', {
  header: 'X-API-Key',
  value: 'shared-secret-token'
}, { ifMatch: 'file:v3' });

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

422

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

Set container group program permission

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

PATCH is also accepted on this endpoint with identical behaviour.

Set or replace the access rule for a single program within a container group. The access value is a rule defining which instances or ports are allowed, not a list of what exists.

Parameters

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

Request Body

Name	Type	Required	Description
program	string	Yes	Program name (for example http, terminal, ssh, files, exec, services, notifications).
access	boolean | number | array | string	Yes	Access rule. Use true/false for boolean, a number for a single port/index, an array of numbers for multiple ports, "8000-8100" for a range, or "*" as a wildcard. For programs files, services, notifications, and exec, only boolean is allowed.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/permissions/admin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{"program": "http", "access": [80, 443]}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.setGroupPermission('507f1f77bcf86cd799439012', 'admin', {
  program: 'http',
  access: [80, 443]
}, { ifMatch: 'file:v3' });

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

422

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

Delete container proxy permissions

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

Remove the proxy permissions configuration for a single container. The container inherits the project-level configuration afterward.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.delete('507f1f77bcf86cd799439012', { ifMatch: 'file:v3' });

200

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

404

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

422

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

Remove container authentication group

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

Delete a single authentication group from the container permissions document.

Parameters

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

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/groups/admin \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.deleteAuthGroup('507f1f77bcf86cd799439012', 'admin', { ifMatch: 'file:v3' });

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

422

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

Remove all permissions for a container group

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

Remove every program-level access rule for a group on a container, while keeping the group itself and its authentication definition intact.

Parameters

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

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/permissions/admin \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.clearGroupPermissions('507f1f77bcf86cd799439012', 'admin', { ifMatch: 'file:v3' });

200

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

422

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

Remove a single program permission for a container group

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

Remove a single program-level access rule from a container group, leaving the rest of the group’s permissions untouched.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
groupName	path	string	Yes	Group name
program	path	string	Yes	Program name (for example http, ssh, files)
if-match	header	string	Yes	file:v<N> ETag precondition. Read current file_version from GET first.

This endpoint takes no request body.

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions/permissions/admin/http \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v3"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.deleteGroupPermission('507f1f77bcf86cd799439012', 'admin', 'http', { ifMatch: 'file:v3' });

200

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

422

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

Hoody identity authentication

The hoody-identity group type authenticates requests against the identity claim returned by Hoody login. Use it whenever you need to gate a proxy on a logged-in Hoody user, since the identity claim is not a JWT and cannot be validated by a jwt group.

A hoody-identity group never carries key material. The operator does not own the signing keyring; Hoody issues and signs the claim, and your group only declares which audience it accepts and any additional policy constraints.

Unlike jwt, password, ip, and token, the hoody-identity type does not have a dedicated /groups/{groupName}/<type> endpoint. It is configured as an entry in the groups map of the full permissions document, so you set it through the replace endpoint (PUT /api/v1/containers/{id}/proxy/permissions or PUT /api/v1/projects/{id}/proxy/permissions), not via setTokenGroup or any other per-type group setter.

hoody-identity group fields

Name	Type	Required	Description
type	string	Yes	Group type discriminator. Use hoody-identity.
audience	string	Yes	Exact audience the identity claim aud must equal. Maximum 256 characters.
sources	array	No	Token source locations. Header-only, in the X-Hoody-Identity- namespace (for example X-Hoody-Identity-User).
allow_types	array	No	Account types allowed. Allowed values: user. Omit to allow every signed-in Hoody account.
users	array	No	Optional user-id allowlist, 24-hex each. Maximum 256 entries.
max_age_seconds	integer	No	Freshness gate on claim iat. Must be >= 300.
expose_type	boolean	No	Also inject X-Hoody-Identity-Type for downstream consumers. Defaults to false.

cURL

curl -X PUT https://api.hoody.com/api/v1/containers/{containerId}/proxy/permissions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v3" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "container": "507f1f77bcf86cd799439012",
    "groups": {
      "admins": {
        "type": "hoody-identity",
        "audience": "https://app.example.com/proxy",
        "allow_types": ["user"],
        "max_age_seconds": 300,
        "expose_type": true
      }
    },
    "permissions": {
      "admins": {
        "terminal": true,
        "files": true
      }
    },
    "default": "deny",
    "enable_proxy": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.api.proxy.containerPermissions.set('507f1f77bcf86cd799439012', {
  project: '507f1f77bcf86cd799439011',
  container: '507f1f77bcf86cd799439012',
  groups: {
    admins: {
      type: 'hoody-identity',
      audience: 'https://app.example.com/proxy',
      allow_types: ['user'],
      max_age_seconds: 300,
      expose_type: true
    }
  },
  permissions: {
    admins: {
      terminal: true,
      files: true
    }
  },
  default: 'deny',
  enable_proxy: true
}, { ifMatch: 'file:v3' });

Note

The hoody-identity group is configured through the replace endpoint because it has no per-type setter of its own. The four fields header, cookie, param, and value belong to the single-value token group at /groups/{groupName}/token and are rejected by validation if supplied to a hoody-identity group.