API Keys

API keys are managed in the Whagons product at Settings > Integrations.

API keys act as the user who created them. They inherit that user's current tenant permissions and workspace visibility, so revoking a user's access or changing their role also affects what their keys can do.

Create a key in Settings

You need the config.integrations permission.

Open Settings → Integrations → API Keys.
Choose Add API Key.
Give the key a name that identifies its system, purpose, and environment.
Choose an expiration: 1 hour, 1 day, 7, 30, 90, or 180 days, 1 year, or never.
Create the key and copy the plaintext value immediately.
Save it in the external system's secret manager.

The full value is shown once. Later, Settings shows only the key's name, final four-character hint, creation date, expiration, last-used date, and enabled state.

Keys begin with whg_live_. Whagons stores a hash rather than the plaintext credential.

Key Lifecycle

State	API behavior
Active	Requests can authenticate if the key has the required tenant and scope.
Inactive	Requests fail with `401`.
Expired	Requests fail with `401`.
Revoked	Requests fail with `401` and the key is hidden from active key lists.

Successful authenticated HTTP requests update the key's last-used timestamp.

Default Scopes

New keys default to:

["ext:read", "ext:tasks:write"]

The current Settings dialog does not expose a scope selector; it issues both external scopes. Keep effective access narrow by using a dedicated key creator with only the required roles, teams, and workspaces.

Scope	Allows
`ext:read`	Read reference data and visible tasks.
`ext:tasks:write`	Create, update, delete, comment, assign, tag, approve, or acknowledge visible tasks when the creator has the matching product permission.
`*`	Compatibility value accepted by the backend for specially provisioned keys; it is not offered by the Settings creation flow.

Disable versus revoke

Use the Enabled switch for a reversible pause. Disabled keys return 401.
Use Delete to revoke the key permanently. The key disappears from the active list and cannot be restored.

Rotation Guidance

Create a replacement key.
Deploy it to the external system.
Confirm successful calls with the new key.
Revoke the old key.

Never paste keys into chat, issue trackers, documentation examples, release notes, or PR bodies.

Create keys through the assistant

The built-in Whagons assistant can list keys or create a key after explicit user approval when the user has integration-management permission.

Disabling and revoking a key should be done in Settings → Integrations. The assistant must never repeat or log a plaintext key after the one-time creation response.

See the API quickstart for the complete first-request flow.