Maison — Roles, policies and groups

Shape permissions on Maison: roles, policies and user groups, each available to one hotel or to all clients (roles and policies may be Maison only). A policy is a list of rules (feature + level) and is never applied to a client directly — a role applies each of its policies at all clients or at named clients (Applies to). Also the feature catalogue and effective-access views. Use when designing who may do what, troubleshooting a 403, or granting a team a bundle of permissions.

Part of the Maison public API. Read the maison-public-api skill first for authentication, discovery and transport details (https://docs.maison-labs.com/skills/maison-public-api/SKILL.md).

When to use

• Set what a policy allows from a description ("can view conversations and analytics but change nothing"): set_policy_rules (Maison policy) or set_client_policy_rules (hotel policy) save the full rule list in one call.
• Create a reusable permission bundle for a hotel — create_client_policy with statements, attach it to a role with attach_client_role_policy.
• Explain a 403 — get_client_user_access (users skill) or get_client_role / get_client_policy effective access.
• Roles and groups available to all clients — create_role (clientId null), create_group, update_group_roles; apply a shared policy at chosen hotels with attach_role_policy and change it with set_role_policy_applies_to.
• Bring a retired role back — restore_role. Page a role's holders past get_role's first 50 — list_role_users, list_role_groups.
• Maison policies end to end — create_policy, set_policy_rules, attach_role_policy; update_policy renames or re-describes; delete_policy once no role applies it.
• Rename a hotel group or drop it — update_client_group, delete_client_group.

Before you start

1. Send x-api-key: <key> on every call; the key only reaches /api/v1.
2. GET /api/v1/tools (or MCP tools/list) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
3. Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

Full input fields for every tool: references/tools.md.

Recommended workflows

Set a policy's rules from what the person describes

1. get_policy (or get_client_policy) for the current rules; list_features (or list_client_features_catalogue) for each feature's id, label and purpose.
2. Map the words to levels: view → READ, change or manage → WRITE, run, send or act → EXECUTE, never or block → DENY. Name the specific features; the every-feature rule (featureId null) only when they mean everything.
3. Ambiguous (which features, which level)? Show the rules as a short Feature / Level list and ask before saving.
4. set_policy_rules (or set_client_policy_rules) with the FULL list: the current rules you keep plus the changes, one rule per feature. A rule left out is removed.

Grant a hotel team a defined set of features

1. list_client_features_catalogue to see which features the hotel's plan allows for roles.
2. create_client_policy with statements: [{ featureId, permission }] (or create_client_role with inline rules; add or remove one later with add_client_role_rule / remove_client_role_rule); a rule names no client.
3. create_client_group with memberIds and roleId, or assign per user with set_client_user_roles.
4. Verify with get_client_group / get_client_role effective access.

Tips

• Levels: READ < WRITE < EXECUTE; DENY wins over any grant at the same scope. A policy holds at most one rule per feature (and at most one every-feature rule), at exactly one of READ, WRITE, EXECUTE or DENY; a higher level includes the lower ones (WRITE already includes READ).
• Nobody can grant a feature level they do not hold themselves on that hotel (no-escalation rule) — a 403 while adding a statement usually means that.
• A rule granting a Maison-only feature (flagged maison_only in list_features), an every-feature rule, and attaching a policy that grants a Maison-only feature all need allow-maison-only WRITE held globally and by name — an ALL wildcard never counts (403 names allow-maison-only). A DENY rule needs nothing extra.

Pitfalls

• The rules tools replace the whole list, and one rule beyond your own access refuses the whole save (403 names the feature and level; nothing changed). One feature at two levels in the list is a 400 (nothing saved).
• add_role_policy, add_client_role_rule and add_client_policy_statement set the feature's one rule: a different level replaces the current rule, the same level changes nothing.
• Each kind has one grant, at the hotel for a row available to that hotel and GLOBAL for a row available to all clients (or Maison only): roles → maison-roles (also attaching policies to a role), groups → groups, policies → policies (and their rules), giving or revoking a role or a membership → maison-users. clients WRITE grants nothing in access management. Read with the same feature at READ.
• A role's own inline rules (add_role_policy, create_role with policies) need GLOBAL policies WRITE; a hotel's rules (set_client_policy_rules, add_client_policy_statement) need policies WRITE on the hotel.
• A policy available to one hotel applies only there; a role available to one hotel applies its policies there only (appliesTo null). A rule input naming a client, region, department or tag is a validation error — scope lives on the role, never on a rule.
• Disabling a role is soft (disable_role); the role's users lose the permissions immediately.
• delete_client_group is 409 while the group has members (pending invitations included) and delete_policy is 409 while a role applies it: empty or detach first.
• unassign_role without linkScope removes the role at every scope; pass linkScope: "global" or a client id to remove one link.

Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send x-api-key.

# REST
curl -X POST "https://maison-labs.com/api/v1/client/<clientId>/policy/<policyId>/statement" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{ "permission": … }'

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_client_policy_statement", "arguments": { "permission": … } } }

// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "add_client_policy_statement", "input": { "permission": … } } }] } } }

Errors are the same everywhere: 401 no/invalid key; 403 forbidden with details.missing (the grants you lack — fall back to the composite's parts or stop); 403 not_entitled (the hotel's plan lacks the feature); 404, 409, 413 too_large, 503. Inputs that fail validation return 400 invalid_input with the Zod issues — fix and retry once.