Skip to main content

Authentication

The Cocktail Manager API supports two kinds of API keys. Both are sent as Bearer tokens in the Authorization header:

curl https://<your-instance>/api/v1/workspaces/<workspaceId>/cocktails \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Workspace API key (default)​

The normal path for integrations: a JWT bound to one workspace with a set of granular permissions.

  • Create one in the workspace under Settings → API Keys — see API keys.
  • Each endpoint's required permission is listed in the API Reference (field Required API-key permission).
  • The workspaceId path parameter must match the key — a key from another workspace is rejected with 403.
  • In the API reference this scheme is called WorkspaceApiKeyAuth.

Instance master key (administration)​

For managing a self-hosted instance. Set via the server environment variable INSTANCE_MASTER_API_KEY; it is not bound to a workspace.

  • Instance-wide: works for every workspace and bypasses per-endpoint permission checks.
  • Intended for instance administration/automation — not for third-party integrations (always use a workspace key with minimal rights there).
  • In the API reference this scheme is called InstanceApiKeyAuth.
Inspect a token

GET /api/v1/me returns what a token can access (workspace, permissions, isMaster). For the master key, workspaceId is null and isMaster is true.

Session-only operations​

A few operations act on the signed-in user's own identity (e.g. leaving a workspace or creating/revoking API keys). These require a logged-in session and accept no API key — neither a workspace key nor the master key. In the API reference they use the SessionCookieAuth scheme.

Response format​

Successful /api/v1 responses are wrapped in a data envelope:

{ "data": { "id": "…", "name": "Old Fashioned", "hasImage": true, "imageUrl": "/api/v1/…/image" } }

Errors are uniform:

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "issues": [ … ] } }

Typical status codes: 400 (validation), 401 (missing/invalid key or session), 403 (missing permission / wrong workspace), 404 (not found), 409 (conflict, e.g. still referenced).

Images​

Image-bearing resources do not include Base64 in JSON; they return hasImage: boolean and imageUrl. imageUrl points to a bytes endpoint (GET …/{id}/image) that you can use directly as <img src>.