Skip to main content
Every /v1 request authenticates with a workspace API key: a machine credential, scoped to one workspace and to explicit permissions.

​
Create a key

Keys are created in the console, under Configuration → API keys:
  1. Open your workspace, go to Configuration.
  2. Under API keys, choose Create key, name it, and pick the scopes it needs.
  3. Copy the key now: it is shown exactly once and stored only as a hash. It cannot be recovered; if you lose it, create another.
A key looks like:
  • live vs test is the environment segment. Use a test key against a test workspace and a live key in production; both authenticate the same way.
  • The first 12 characters (wdy_live_x7Q…) are the prefix the console lists: enough to recognise a key, never enough to use it.

​
Send it

As a bearer token, on every request:
GET /v1/me is the call to make first. It returns the workspace the key belongs to and the scopes it was granted:
Any key failure (missing, malformed, unknown, revoked or expired) is the same 401 wondeya.api_key.invalid, on purpose: distinguishing them would be an oracle. A request whose key lacks a required scope is a 403 wondeya.api_key.scope_missing.

​
Scopes

A key is granted permissions per area and per direction. Grant only what an integration needs. The appearance theme rides landings:* (it is part of what the pages surface configures). A key with no scope is refused: “no scope” must never read as “every scope”.

​
Rotate

A workspace keeps at most two active keys at once, so a rotation has an overlap window:
  1. Create a second key with the same scopes.
  2. Deploy it everywhere the old one was used.
  3. Revoke the first key in the console.
Revoking is immediate. There is no “regenerate”: a rotated key is a new key, and the old secret is gone the moment it is revoked.