Authentication
How external integrations authenticate with Whagons.
Whagons supports API keys, first-party user sessions for a small user-facing surface, and agent credentials discovered through auth.md.
API Keys
Server-to-server integrations should use tenant API keys from Settings > Integrations.
Send the key with either header:
X-API-Key: whg_live_...or:
Authorization: Bearer whg_live_...API keys are tenant-scoped. They are stored hashed and the plaintext value is shown only once when created.
Each key acts as its creator. Endpoint responses and writes are constrained by that user's current permissions, team membership, workspace visibility, and task visibility.
Do not send API keys in query parameters.
Agent Auth
AI agents can discover Whagons authentication from the beta agent-auth service:
GET https://gon.whagons.com/auth.mdStructured discovery is available at:
GET https://gon.whagons.com/.well-known/oauth-protected-resource
GET https://gon.whagons.com/.well-known/oauth-authorization-serverAgent access tokens use:
Authorization: Bearer whg_agent_...Agent tokens have their own registration, expiry, revocation, and audit trail, but requests act on behalf of the Whagons user who approved the agent. Endpoint responses and writes are constrained by that user's current permissions, team membership, workspace visibility, and task visibility.
Read auth.md agent access for the user-claimed flow and token lifecycle.
User Session Auth
The /api/v1/me/tenants endpoint requires an authenticated user session rather than an API key. It is intended for first-party client experiences that already have Whagons/Firebase identity.
Scopes
| Scope | Allows |
|---|---|
ext:read | Read external reference data and visible task data. |
ext:tasks:write | Create, update, delete, comment on, assign, tag, approve, and acknowledge visible tasks. |
* | Backend compatibility value for specially provisioned API keys; not issued by the current Settings flow or agent flow. |
Required Scope by Endpoint
| Endpoint | Scope |
|---|---|
GET /api/v1/workspaces | ext:read |
GET /api/v1/spots | ext:read |
GET /api/v1/users | ext:read |
GET /api/v1/categories | ext:read |
GET /api/v1/statuses | ext:read |
GET /api/v1/priorities | ext:read |
GET /api/v1/teams | ext:read |
GET /api/v1/templates | ext:read |
GET /api/v1/tags | ext:read |
GET /api/v1/tasks | ext:read |
GET /api/v1/task-comments | ext:read |
GET /api/v1/task-assignments | ext:read |
GET /api/v1/task-tags | ext:read |
GET /api/v1/task-logs | ext:read |
POST /api/v1/tasks | ext:tasks:write |
PATCH /api/v1/tasks | ext:tasks:write |
DELETE /api/v1/tasks | ext:tasks:write |
POST /api/v1/task-comments | ext:tasks:write |
POST /api/v1/task-assignments | ext:tasks:write |
POST /api/v1/task-tags | ext:tasks:write |
POST /api/v1/task-approval | ext:tasks:write |
POST /api/v1/task-acknowledgment | ext:tasks:write |
GET /api/v1/me/tenants | First-party user session |
Error Shape
Errors currently return JSON with an error field:
{
"error": "Unauthorized"
}Common statuses:
400: missing required parameter or invalid JSON.401: missing credential, invalid credential, expired credential, inactive key, wrong tenant, or missing required scope.
The agent discovery challenge on protected API responses is part of the in-progress gateway alignment. Agent clients should currently start from the published auth.md URL rather than depending on a WWW-Authenticate header.