Inloggen

Authenticatie

API-authenticatie, sessielevenscyclus en best practices voor beveiliging

Cliqer authenticeert met een httpOnly sessiecookie (session_token), aangemaakt door POST /api/auth/login. Browsers sturen die automatisch mee bij elk verzoek; server-to-servertools bewaren hem in een cookie jar. Teams met Studio 8K en Enterprise kunnen daarnaast API-sleutels aanmaken voor server-to-servertoegang, verstuurd als Authorization: Bearer cliqer_<key>, zie Authenticatie met API-sleutels hieronder.

Sessiemodel

ReferentieWaar die staatHoe je die krijgt
Sessiecookie (session_token)httpOnly, Secure cookie op je Cliqer-hostIngesteld door POST /api/auth/login, automatisch geroteerd door de server

De cookie is HttpOnly en dus niet leesbaar vanuit JavaScript. De levensduur volgt de TTL van de serversessie en wordt ongemerkt verlengd telkens wanneer je GET /api/auth/me aanroept. Er is geen apart refresh-endpoint om aan te roepen: een langlevende client netjes ingelogd houden betekent periodiek GET /api/auth/me aanroepen.

Sessielevenscyclus

De sessie gebruiken

Browsers voegen de cookie automatisch toe. Bewaar bij server-to-serverclients de cookie die het login-antwoord instelt en stuur die mee bij volgende verzoeken:

# Save the session cookie on login, then reuse it
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

Authenticatie met API-sleutels

Teams met Studio 8K en Enterprise kunnen langlevende API-sleutels aanmaken voor server-to-servertoegang, als alternatief voor het bewaren van de inloggegevens van een gebruiker. Je maakt ze aan en trekt ze in via het dashboard onder Team → API-sleutels (/dash/team/api-keys); voor het aanmaken is de teameigenaar nodig (of een aangepaste rol met de machtiging voor API-sleutels). Sleutelbeheer is alleen beschikbaar in de abonnementen Studio 8K en Enterprise.

De pagina API-sleutels in het dashboard, onder Team in de zijbalk, met de knop Sleutel aanmaken en een notitie over het versturen van een sleutel als Bearer-token

Een sleutel wordt eenmalig getoond bij het aanmaken, in de vorm cliqer_<prefix>_<secret>. Bewaar hem veilig: hij kan niet worden hersteld, dus trek hem in en maak een nieuwe aan als je hem kwijtraakt. Stuur hem als Bearer-token mee naar elk REST-endpoint dat een sessie accepteert:

curl -X GET "$BASE_URL/api/licenses/status?license_key=YOUR_LICENSE_KEY" \
  -H "Authorization: Bearer cliqer_ab12cd34_your_secret_here"

API-sleutels werken alleen op de REST-endpoints. De WebSocket, inclusief diabesturing, vereist een sessietoken.

De sleutel authenticeert als de gebruiker die hem heeft aangemaakt, beperkt tot het team en abonnement van die gebruiker. Een ingetrokken of onbekende sleutel geeft 401 terug, precies zoals een ontbrekende sessie. Endpoints die alleen voor beheerders zijn, weigeren API-sleutels altijd met 403. Voor sleutels gelden dezelfde rate limits als voor sessieverzoeken.

Behandel een API-sleutel als een wachtwoord. Iedereen die hem in handen heeft, kan via gedocumenteerde endpoints namens je account handelen totdat je hem intrekt.

Inloggen

Wissel gebruikersgegevens in voor een sessie. Bij succes stelt het antwoord de cookie session_token in.

Endpoint: POST /api/auth/login

ParameterTypeVerplichtBeschrijving
emailstringJaE-mailadres van de gebruiker (een WordPress-gebruikersnaam wordt ook geaccepteerd)
passwordstringJaWachtwoord van de gebruiker
otpstringNeeTOTP-code, als het account een authenticator-app gebruikt
email_otpstringNeeGemailde pincode, als het account 2FA via e-mail gebruikt
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

Antwoord (succes): stelt de cookie session_token in en geeft de sessiemetadata terug.

{
  "data": {
    "expires": 604800000
  }
}

Antwoord (2FA vereist): een 200-signaal voor de controlflow, geen fout. Verstuur POST /api/auth/login opnieuw met dezelfde inloggegevens plus otp (authenticator) of email_otp (gemailde pincode).

{
  "requires_otp": true,
  "method": "totp",
  "email_sent": false
}

method is totp, email of both. Bij email mailt de server een pincode en geeft email_sent aan of die e-mail is verstuurd. Een account met both logt in met de authenticatorcode (otp); de gemailde pincode is voor zo'n account geen inlogfactor.

Ongeldige inloggegevens geven 401 terug, net als een onjuiste of verlopen TOTP-code. Een onjuiste of verlopen gemailde pincode geeft ook 401 terug, met dezelfde melding als een onjuist wachtwoord. Een lid van een organisatie die single sign-on vereist, krijgt 403 en moet inloggen met SSO (zie de SSO-FAQ).

Sessierotatie

Er is geen apart refresh-endpoint. De server roteert de cookie session_token voor je: als een sessie dicht genoeg bij het verlopen is, antwoordt GET /api/auth/me met een nieuwe Set-Cookie naast het profiel. Een client die een cookie jar bijhoudt en periodiek GET /api/auth/me aanroept, blijft zonder extra werk onbeperkt ingelogd.


Huidige gebruiker

Geeft het profiel van de geauthenticeerde gebruiker terug, of { "data": null } als er geen geldige sessie is (geschikt voor anonieme gebruikers, nooit een 401).

Endpoint: GET /api/auth/me

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

Antwoord:

{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "uuid",
    "tfa_method": "none",
    "is_admin": false
  }
}

Uitloggen

Beëindigt de sessie voor de huidige cookie en verwijdert de cookie uit de browser.

Endpoint: POST /api/auth/logout

curl -X POST "$BASE_URL/api/auth/logout" -b cookies.txt -c cookies.txt

Antwoord:

{
  "success": true
}

Best practices voor beveiliging

Aanbevolen beveiligingsmaatregelen
  1. Gebruik alleen HTTPS: de sessiecookie is Secure; alle verzoeken moeten TLS 1.2+ gebruiken.
  2. Lees de cookie nooit uit met JavaScript: hij is bewust HttpOnly; houd dat zo.
  3. Vernieuw proactief: roep op langlevende tabbladen GET /api/auth/me aan voordat de sessie verloopt; de server roteert de cookie voor je.
  4. Log uit om in te trekken: POST /api/auth/logout beëindigt de sessie direct aan de serverkant.
  5. Bewaar inloggegevens, geen sessies: server-to-serverintegraties horen de inloggegevens in een secretmanager te bewaren en opnieuw een sessie op te zetten, en de cookie nooit in de broncode op te slaan.
Zie Beveiligingsoverzicht voor de beveiligingsfuncties voor Enterprise.