Organizations and workspaces

Workspace = event, in practice — the name in the code is workspace, but everything that applies to "event" in the rest of this documentation (participant, PDV, cashier) refers to a workspace created here.

Organizations

Endpoint	What it does
GET /v1/management/organizations	Lists organizations where the authenticated manager has an active role.
POST /v1/management/organizations	Creates an organization; the creator becomes owner. slug is optional — if omitted, the API generates one from the name.
PATCH /v1/management/organizations/{organizationId}	Only owner can change the name. Slug and the manager's role are read-only.
DELETE /v1/management/organizations/{organizationId}	Only owner. Closes the organization and archives every workspace in it.

Available regions

Endpoint	What it does
GET /v1/management/regions	Lists region codes that have at least one active cluster — this is the list that feeds the region selector when creating a workspace.

Workspaces (events)

Endpoint	What it does
GET /v1/management/organizations/{organizationId}/workspaces	Lists the organization's workspaces.
POST /v1/management/organizations/{organizationId}/workspaces	Creates and provisions a workspace in a region. owner/admin only.
PATCH /v1/management/organizations/{organizationId}/workspaces/{workspaceId}	Updates name, timezone, startsAt/endsAt. Region and currency are immutable after creation.
POST .../workspaces/{workspaceId}/provisioning/retry	Retries regional provisioning when it failed (status=failed).
DELETE .../workspaces/{workspaceId}	Archives the workspace (terminal — there's no "reactivate").

Example: create a workspace

curl

curl -X POST http://127.0.0.1:8787/v1/management/organizations/{organizationId}/workspaces \
  -H "Authorization: Bearer <manager accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Festival",
    "homeRegion": "br-east-1",
    "timezone": "America/Sao_Paulo",
    "currencyCode": "BRL"
  }'

JavaScript

const response = await fetch(
  `http://127.0.0.1:8787/v1/management/organizations/${organizationId}/workspaces`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Summer Festival",
      homeRegion: "br-east-1",
      timezone: "America/Sao_Paulo",
      currencyCode: "BRL",
    }),
  },
);
const workspace = await response.json();

Python

import requests

response = requests.post(
    f"http://127.0.0.1:8787/v1/management/organizations/{organization_id}/workspaces",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Summer Festival",
        "homeRegion": "br-east-1",
        "timezone": "America/Sao_Paulo",
        "currencyCode": "BRL",
    },
)
workspace = response.json()

Provisioning is synchronous from the client's point of view

POST .../workspaces calls the chosen region's wallet-api synchronously, within the same request — the client already gets status: "active" or status: "failed" in the response, with no need to poll. If it fails (region momentarily unavailable, for example), the global record and the slug already exist; use the retry endpoint, don't create it again.

eventCode — the event's short code

Every workspace response includes eventCode, in the format AXY-9898 (3 letters excluding I/O, 4 digits excluding 0/1 — avoids visual ambiguity). This is the code the participant types or scans via QR to find the event and activate their own wallet in it — see Find an event and activate a wallet. It's generated automatically when the workspace is created; there's no way to choose or edit it.