Authentication
The Happklaar API uses Personal Access Tokens (PATs) as the sole authentication mechanism for the public API. There is no session-cookie auth on api.happklaar.nl — bearer tokens only.
Overview
Every request to a protected endpoint must include an Authorization header:
Code
The API does not accept cookies. Set credentials: 'omit' on all fetch calls made from browser clients. Session-based auth (app.happklaar.nl) is a separate subdomain and is not in scope here.
Creating a token
Tokens are issued through the Happklaar app:
app.happklaar.nl → Account → API Keys
When you create a token, the interface asks for a name. The system uses the format:
Code
Examples: iOS on iPhone15,2 / Apr 2026, Android on SM-S918B / Apr 2026. If the platform cannot be determined, the name falls back to Mobile device / Apr 2026.
All tokens start with the prefix hk_. Copy the full token value immediately after creation — it is shown only once.
One token per device
The API enforces a one-token-per-device invariant. When you request a new token from a device that already has one issued under the same derived name, the prior token is automatically revoked before the new one is issued. You will not accumulate stale tokens for the same device.
Using a token
Include the token as a bearer credential on every request:
Code
For browser fetch calls:
Code
The credentials: 'omit' setting is required. Do not use credentials: 'include' — it sends cookies that have no effect on the API subdomain and can cause unexpected behavior.
Scopes and lifetime
Tokens issued through app.happklaar.nl do not expire on their own. The only way a token loses validity is explicit revocation — either by you, or by a policy-driven revoke (such as a password change).
There is no token refresh flow. If your token is revoked, generate a new one through the API Keys interface.
Rotating and revoking
Manage your tokens at:
app.happklaar.nl/app/profile/security
The Security page lists every active token as a row in the Devices table. Each row has a Revoke action that deletes that token immediately. A separate "Sign out everywhere" button deletes all tokens for your account.
If you suspect a token has been compromised, revoke it immediately from the Security page and generate a replacement.
When try-it becomes available
The interactive try-it playground in these docs (which lets you run API calls directly from the browser) is not enabled yet. It will be enabled in a future release once the required CORS and policy changes are in place. Until then, use the curl examples in each endpoint reference.
Error responses
A missing or invalid token returns a 401 Unauthenticated response using the RFC 9457 envelope:
Code
See Errors for the full problem type reference.