Authentication

wede accepts two credentials. Use the one that matches where your code runs.

	API key	Session token
For	Server-to-server integrations	People using an app, a device or the dashboard
Header	`x-wede-api-key: wede_live_...`	`Authorization: Bearer <token>`
Obtained	Dashboard settings or the API, by a `company_admin`	`POST /v1/auth/login` with email and password
Permissions	Fixed integration scope (below)	The user’s role
Where it may live	Server only	Device or browser

If a request carries both headers, wede uses the session token. The API accepts cross-origin requests from any origin, because it authenticates only by these headers and never by cookies. A web app can therefore call wede from the browser with the user’s session token, for example through the JavaScript SDK. An API key never goes in a browser.

API keys

API keys start with wede_live_ (production) or wede_test_ (sandbox), followed by 32 hexadecimal characters. wede stores only a SHA-256 hash of each key, so a key is shown in full only once, when it is created or rotated.

curl https://api.wede.pt/v1/events \
  -H "x-wede-api-key: $WEDE_API_KEY"

An API key is a server-side secret. Never put it in a browser, a mobile app, a public repository or a log. Anyone who can read an app bundle can extract a key from it. Apps use session tokens.

What an API key can do

An API key is your integration credential. It covers the full integration cycle:

Area	Endpoints
Events	`POST /v1/events`, `GET /v1/events`, `GET /v1/events/:event_id`
Offline sync	`POST /v1/sync/batch`, `GET /v1/sync/status`
Webhooks	`GET /v1/webhooks`, `POST /v1/webhooks`, `DELETE /v1/webhooks/:webhook_id`, `POST /v1/webhooks/:webhook_id/test`
Event types	`GET /v1/catalog`, `GET /v1/catalog/equipment`
Connectivity	`GET /v1/connectivity/status`, `POST /v1/connectivity/report`
Zones	`GET /v1/tenant/zones`, `GET /v1/tenant/zones/:zone_code`
Tenant	`GET /v1/tenant/me`, `GET /v1/tenant/usage`, `GET /v1/tenant/billing`
Sandbox	`POST /v1/sandbox/simulate-connectivity` (sandbox keys only)

An API key cannot create, update or delete zones, and cannot manage teams, dispatch, missions, users, API keys or catalog entries. Those operations need a session token with the right role. With an API key they return 403 forbidden. API key requests are limited per tenant and per minute (your tenant or plan limit, 500 by default). Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; above the limit wede returns 429 rate_limited with Retry-After. See Retries and rate limiting.

Sandbox keys

A wede_test_ key works against the sandbox:

Every event is stored with the environment of the key that created it (production or sandbox), and a key reads only its own environment.
Sandbox events never reach a real recipient. wede simulates delivery with the same channel decision as production and records the result on the event and its lifecycle.
Sandbox activity never counts toward usage or billing.
The same idempotency_key can exist once in each environment.
POST /v1/sandbox/simulate-connectivity works only with a sandbox key (403 sandbox_key_required otherwise) and changes only the simulated state of a zone, never the real one. POST /v1/connectivity/report with a sandbox key also changes only the sandbox state.
Webhook deliveries carry "environment": "sandbox" or "environment": "production".

Creating and rotating keys

Managing keys needs a session token with the api_keys:manage permission (the company_admin role).

Endpoint	What it does
`GET /v1/tenant/api-keys`	Lists active keys, with their prefix, environment, last use and grace expiry. Never the full key
`POST /v1/tenant/api-keys`	Creates the first key of an environment: `{ "environment": "production" }` or `"sandbox"`. Returns `409 conflict` if that environment already has an active key
`POST /v1/tenant/api-keys/rotate`	Issues a new key and keeps the previous one valid for a grace period

curl -X POST https://api.wede.pt/v1/tenant/api-keys/rotate \
  -H "Authorization: Bearer $WEDE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "production", "grace_hours": 24 }'

{
  "message": "API key rotated successfully.",
  "new_key": "wede_live_...",
  "grace_hours": 24,
  "note": "Previous key remains valid for 24 hours."
}

grace_hours defaults to 24. Deploy the new key everywhere within the grace period; after it, the previous key stops working.

Session tokens

A person signs in with email and password and receives a session token:

curl -X POST https://api.wede.pt/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "..." }'

{
  "token": "eyJhbGciOi...",
  "expires_in": 28800,
  "user": {
    "id": "user-uuid",
    "email": "you@example.com",
    "name": "Your Name",
    "rbac_level": "operational_supervisor",
    "verticals": ["healthcare"]
  }
}

Send it as a bearer token:

curl https://api.wede.pt/v1/missions \
  -H "Authorization: Bearer $WEDE_SESSION_TOKEN"

A token is valid for 8 hours (expires_in is in seconds). After that the API returns 401 and the user signs in again.
A token stops working at once when the user is suspended or the session is revoked.
Five consecutive failed sign-in attempts lock the account for 15 minutes. While locked, sign-in returns 429 account_locked with locked_until.
A session reads production data by default. Where an endpoint supports it, pass environment=sandbox to read sandbox data.

Roles

What a session token can do depends on the user’s role in your tenant. A request outside the role returns 403 forbidden.

Role	For	What it can do
`company_admin`	Tenant administrators	Everything in the tenant: users, API keys, billing, events, sync, webhooks, event types, zones, teams, dispatch, missions, parsers, dispatch settings and the audit log
`company_tech`	Technical teams	Send and read events, sync, view webhooks and API keys, report and read connectivity, manage zones, teams, event types, parsers and missions, dispatch settings. No dispatch, no billing
`operational_supervisor`	Control rooms and supervisors	Read events, sync, read connectivity, view zones, dispatch teams, view teams, manage missions, parsers, view billing
`field_operator`	Field teams on a device	See the missions of their own teams (`GET /v1/missions/my`) and update their status, update their own location, register and sync a device, view zones, report connectivity, sync operations captured offline
`corporate_client`	Client organisations	Send and read events, sync, view zones, dispatch teams, view teams and missions, parsers, view billing

The API key’s integration scope works as a role of its own (api_user), described in What an API key can do. wede staff roles exist for operating the platform. They never see event content: not the payload, not the metadata, not your event types nor your catalog; only the vertical, priority, channel, timestamps and whether the type sends a team.

Good practice

Keep API keys in environment variables or a secret manager, never in code.
Use a wede_test_ key in development and CI.
Rotate keys when a person with access leaves or a key may have leaked, using the grace period to avoid downtime.
Give each person the least powerful role that fits their work.
All traffic to https://api.wede.pt is encrypted in transit over HTTPS.

Introduction

Core Concepts

Examples by Vertical

API keys

What an API key can do

Sandbox keys

Creating and rotating keys

Session tokens

Roles

Good practice

​API keys

​What an API key can do

​Sandbox keys

​Creating and rotating keys

​Session tokens

​Roles

​Good practice

API keys

What an API key can do

Sandbox keys

Creating and rotating keys

Session tokens

Roles

Good practice