---
name: "maison-account"
description: "Discover what the calling API key may do before planning anything: who the key belongs to, whether they are Maison staff, every feature grant they hold globally or per hotel, and which hotel ids they can act on; and manage the caller's own API keys and connected apps. Use at the start of any session with the Maison public API, when a call returned 403, or when choosing which hotel id to pass. Also read or clear your own operator notices (agent replies, guest messages in conversations you handle, conversations needing attention, agent notices). Tools: disable_my_api_key, get_notice_summary, list_my_api_keys, list_my_connected_apps, list_notices, mark_notices_read, revoke_my_connected_app, whoami."
license: "Proprietary. Use with a Maison API key under the Maison terms of service."
metadata:
  author: "maison-labs"
  version: "1.0.0"
  category: "account"
  api-base: "https://maison-labs.com"
  openapi: "https://maison-labs.com/api/v1/openapi.json"
  docs: "https://docs.maison-labs.com/skills/maison-account/"
---

# Maison — Account and discovery

Discover what the calling API key may do before planning anything: who the key belongs to, whether they are Maison staff, every feature grant they hold globally or per hotel, and which hotel ids they can act on; and manage the caller's own API keys and connected apps. Use at the start of any session with the Maison public API, when a call returned 403, or when choosing which hotel id to pass. Also read or clear your own operator notices (agent replies, guest messages in conversations you handle, conversations needing attention, agent notices).

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

- First call of a session: learn the user, grants and reachable client ids.
- After a 403: compare `details.missing` with the grants `whoami` reports.
- To choose a `clientId` for client-scoped tools when the user did not name one.
- Catch up on what needs you — `get_notice_summary`, `list_notices`, then `mark_notices_read` (by `ids`, subject or `category`).
- Review or stop your own access — `list_my_api_keys` / `disable_my_api_key`, `list_my_connected_apps` / `revoke_my_connected_app` (no grant needed; they only ever act on you).

## 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

| Tool | What it does | REST | Needs |
| --- | --- | --- | --- |
| `disable_my_api_key` | Disable one of your own API keys (an id from `list_my_api_keys`); calls with it are refused at once — including this call's key if you name it. | `DELETE /api/v1/me/apikey/{keyId}` | a valid API key; destructive |
| `get_notice_summary` | Your unread operator notices by category, across every hotel you can read conversations of: agent replies (your Maison agent sessions), guest messages (conversations you are handling, with message and conversation counts), conversations needing attention, and agent notices (notify_operator actions), each with per-hotel counts, plus `total`. | `GET /api/v1/notices/summary` | chat-logs READ (any); read-only |
| `list_my_api_keys` | Your own API keys, masked (prefix and last 4 characters — never the key itself), each with its description, creation, last use and whether it is disabled. | `GET /api/v1/me/apikeys` | a valid API key; read-only |
| `list_my_connected_apps` | The apps you have connected to your Maison account with OAuth (your active consents): each with the app, the scopes you granted (grouped by area), the hotels it may act on (`all` or a list), when you granted it and when it was last used. | `GET /api/v1/me/connectedapps` | a valid API key; read-only |
| `list_notices` | Your unread operator notices, newest first: id, category, tone, summary, subject (an agent session, a conversation or an agent execution), hotel, count and times, plus `subjectTitle` (an agent session's title, null otherwise) and `clientName` (the hotel's name, null without one). | `GET /api/v1/notices` | chat-logs READ (any); read-only |
| `mark_notices_read` | Mark your unread operator notices read. | `POST /api/v1/notices/read` | chat-logs READ (any) |
| `revoke_my_connected_app` | Revoke one of your own OAuth consents (a grant id from `list_my_connected_apps`): the app's access tokens are refused within 30 seconds and it cannot refresh; connecting again asks for consent again. | `POST /api/v1/me/connectedapp/{grantId}/revoke` | a valid API key; destructive |
| `whoami` | The user behind the API key, whether they are Maison staff, every feature grant they hold (global or per client) and the client ids they can act on. | `GET /api/v1/me` | a valid API key; read-only |

Full input fields for every tool: [references/tools.md](references/tools.md).

## Recommended workflows

### Start a session

1. Call `whoami` (GET /api/v1/me). Note `isMaisonAdmin`, `grants[]` and `clientIds[]`.
2. Call `GET /api/v1/tools` to see the catalogue filtered to this key — every tool listed is executable somewhere; client-scoped ones still need a permitted `clientId`.
3. If exactly one client id is reachable, use it by default; otherwise ask the user which hotel.

## Tips

- `grants[].global` is null for a feature the user holds only on specific clients; `clients` maps client id → level.
- A level of EXECUTE implies WRITE implies READ.

## Pitfalls

- Do not infer permissions from a tool being present in the OpenAPI document — the document is public and lists everything; only `GET /api/v1/tools` is filtered.
- `disable_my_api_key` on the key you are calling with stops this session's key at once — use another credential to continue.

## Calling conventions

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

```bash
# REST
curl -X DELETE "https://maison-labs.com/api/v1/me/apikey/<keyId>" -H "x-api-key: $MAISON_API_KEY"
```

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

```json
// 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": "disable_my_api_key", "input": {} } }] } } }
```

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.