Authentication and scopes
Platform API tokens, scopes and what a token can see.
Send the token in the Authorization header of every request:
Authorization: Bearer wyc_live_...
Accept: application/jsonTokens starting with wyc_live_ work with real data; wyc_test_ tokens only with test data.
Creating a token
An administrator of a company on the Automate package creates tokens at Settings > API tokens in the Platform dashboard. When creating a token you choose:
- a name, so you can recognise it later;
- its scopes (below);
- live or test mode;
- optionally an expiry date and an IP allowlist (to be confirmed).
The token value is shown once. Store it in your secret manager, never in your code or your repository.
What a token can do
A request only succeeds when all of these allow it:
| Check | Where it is set |
|---|---|
| The token's company | Chosen when creating the token. Other companies do not exist for it. |
| The token's scopes | Chosen when creating the token. |
| The owner's permissions | The role of the person who created the token, checked live on every request. |
| The company's package | The API needs the Automate package. When a company downgrades, its tokens stop working. |
Objects outside the token's company return 404, not 403, so a token cannot find out they exist.
A token stops working when its owner leaves the company, when it expires or when it is revoked in the dashboard.
Scopes
Every endpoint in the API reference names the scope it needs.
| Scope | Allows |
|---|---|
company:read | Retrieve the company, its package and its totals |
allocations:read | List and retrieve allocations, including status and verification |
plantings:read | List and retrieve plantings and their proof dossier |
projects:read | List and retrieve projects |
recipients:read | List and retrieve recipients (personal data) |
recipients:write | Create, update and delete recipients, assigning trees to them |
gift-codes:read | List and retrieve gift codes |
gift-codes:write | Create and revoke gift codes |
certificates:read | List and retrieve certificates and their download URLs |
webhooks:manage | Manage webhook endpoints and redeliver events |
events:read | Read the event log |
Without recipients:read, personal data is left out of every response.
GET /v2/me returns the token's company, owner, scopes and limits.
Legacy v1 tokens
Tokens created in the old woodyou.care dashboard keep working on API v1 only. They cannot be used on v2; create a new Platform token instead.