Concepts

The Whagons API is tenant-scoped and operations-focused. Integrations usually read reference data, map external records to Whagons IDs, then create tasks.

Tenant

A tenant is a Whagons customer or workspace environment. Most API calls require a tenantId.

API keys belong to one tenant. A key cannot be used against another tenant.

API Key

API keys are long-lived server-to-server credentials created by tenant admins in Settings > Integrations.

Keys:

start with whg_live_;
are shown only once;
are stored as hashes;
can expire;
can be revoked or deactivated;
carry scopes.

An API key acts as the user who created it. Reads and writes still respect that user's current permissions, team membership, workspace visibility, and task visibility. If that user is removed, loses access, or is deleted, the key loses that access too.

Scope

Scopes define what a key can do.

Scope	Meaning
`ext:read`	Read reference data and visible task data.
`ext:tasks:write`	Create, update, delete, comment on, assign, tag, approve, and acknowledge visible tasks.
`*`	Compatibility scope accepted for specially provisioned keys, not offered in the current Settings key flow.

Settings-issued keys currently receive both standard scopes. Use a dedicated, least-privilege Whagons user to bound effective access.

Reference Data

Reference data is the set of Whagons IDs an integration needs before it writes work.

Typical flow:

Read workspaces.
Read spots or users if needed.
Store the relevant Whagons IDs in the external system.
Use those IDs when creating tasks.

Task

A task is operational work inside a workspace. External task creation uses the same task creation policy as Whagons product flows so tasks participate in normal assignment, visibility, and lifecycle rules.

Convex IDs and Legacy IDs

Responses may include Convex document IDs and sometimes pgId legacy identifiers. Use Convex IDs for new API requests unless a specific endpoint says otherwise.