Authentication

Authenticate API requests using OAuth 2.0 Bearer tokens or scoped API keys.

The WundertreOS API supports two authentication methods. Use whichever fits your integration model.

Method	Best for	Header
OAuth 2.0 Bearer token	Third‑party apps acting on behalf of a WundertreOS user (Zapier, Make, your own SaaS)	`Authorization: Bearer <token>`
API key	First‑party integrations, server‑to‑server scripts, internal automation	`X-API-Key: <key>`

Both methods authenticate to a single organization and are checked against the same scope rules. Bearer tokens and API keys are stored only as SHA‑256 hashes server‑side — the raw value is shown to you exactly once at creation.

1. OAuth 2.0 Bearer tokens

This is the same flow used by the official Zapier app. Tokens are scoped to a single organization and a set of scopes, and expire 1 hour after issuance. Use the accompanying refresh_token to mint a new access token without re‑prompting the user.

Bearer tokens cannot be generated manually

Bearer tokens are issued automatically through the OAuth 2.0 flow when connecting external apps such as Zapier. They cannot be generated manually. If you are testing the API directly or building a custom integration, use an API key instead.

There are two ways to obtain a Bearer token:

a. Connect through Zapier (no code)

When a user connects your Zap to WundertreOS, Zapier handles the OAuth dance for you. The Zap receives a fresh access token automatically — see the Zapier connect guide.

b. Direct OAuth flow

This section is for developers building applications that connect to WundertreOS on behalf of their users. If you just want to call the API directly or test endpoints, skip to API keys — that's the right method for you.

If you're building your own integration, run a standard OAuth 2.0 authorization‑code flow (PKCE S256 supported and recommended for public clients):

Redirect the user to GET /oauth-authorize (reference)
The user picks an organization and approves the requested scopes
WundertreOS redirects back to your redirect_uri with a code and your state
Exchange the code for tokens at POST /oauth-token (reference)

Example request

bash

curl -X GET \
  'https://api.wundertreos.com/functions/v1/api-contacts?limit=10' \
  -H 'Authorization: Bearer 8f3c2a1d9e7b4f6a5c2d1e0f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b'

2. API keys

API keys are long‑lived, organization‑scoped credentials issued from the WundertreOS dashboard under Settings → Integrations & API. The raw key is an opaque random string; the dashboard shows it once and stores only its hash.

Pass the key in the X-API-Key header:

bash

curl -X GET \
  'https://api.wundertreos.com/functions/v1/api-contacts?limit=10' \
  -H 'X-API-Key: YOUR_API_KEY'

Each call updates the key's last_used_at timestamp so you can audit activity from the dashboard.

Treat API keys like passwords

Never commit keys to source control or ship them in client‑side code. Use server‑side env vars and revoke keys from the dashboard if you suspect exposure.

Choosing a method

Distributing to many users? Use OAuth.
One organization, one integration, one server? Use an API key.
Both work simultaneously — pick per integration.

Errors

If authentication fails you'll receive HTTP 401 with:

json

{
  "error": "unauthorized",
  "message": "Invalid or unknown access token."
}

Missing or insufficient scope returns HTTP 403:

json

{
  "error": "forbidden",
  "message": "Scope 'contacts:write' is required."
}

PreviousIntroduction Next Rate Limits & Best Practices