API authentication
There is one identity — a JWT for a real user — delivered two ways. Browsers receive it as httpOnly cookies and must send a CSRF header on mutations. Programmatic clients carry the same access token in an Authorization: Bearer header, which a browser can never auto-attach cross-site, so it is CSRF-exempt. This page shows the exact wire shape for each.
Bearer token (recommended for programmatic)
GET /api/v1/projects/{projectId}/certificates
Host: cap.example.com
Authorization: Bearer <access_token>
Accept: application/json
- Token: a JWT access token obtained from
POST /api/v1/auth/login(see below). Default TTL 15 minutes. - Authorization: the token's user's org role + project roles — there is no separate credential scope.
- CSRF: not required (no cookies ride the request).
Full workflow and CI/CD examples: Programmatic access.
curl
TOKEN=$(curl -fsS -X POST https://cap.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"ci-bot","password":"..."}' | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" \
https://cap.example.com/api/v1/projects/$PID/certificates
HTTP client libraries
- Go
net/http:req.Header.Set("Authorization", "Bearer "+token). - Python
requests:headers={"Authorization": f"Bearer {token}"}. - TypeScript
ky:ky.create({ headers: { Authorization: `Bearer ${token}` }}).
Cookie (browser)
When a user logs in through the UI, the backend sets three cookies. The UI sends "cookie_only": true in the login body, so no access or refresh token is returned in the body for the browser flow — only the CSRF token is:
| Cookie | Path | Flags | Purpose |
|---|---|---|---|
access_token | / | HttpOnly, SameSite=Lax, Secure* | JWT access token (15 min default). Its cookie Max-Age is deliberately the refresh TTL, so the cookie outlives the token and the client can refresh. |
refresh_token | /api/v1/auth | HttpOnly, SameSite=Lax, Secure* | Refresh token (7 days default). |
csrf_token | / | SameSite=Lax, Secure*, readable by JS | CSRF token to mirror into the header. |
* Secure is set when the server terminates TLS itself, or when server.secure_cookies is enabled for a TLS-terminating proxy in front of it. All three cookies live as long as the refresh token (7 days by default).
CSRF double-submit
Every cookie-authenticated mutation (POST/PUT/PATCH/DELETE) must echo the csrf_token cookie value in X-CSRF-Token:
POST /api/v1/projects/{projectId}/certificates
Cookie: access_token=...; csrf_token=XXXX
X-CSRF-Token: XXXX
Content-Type: application/json
{ ... }
The backend compares header vs cookie on every mutation. Missing cookie, missing header or mismatch → 403. GET requests never need CSRF. Bearer-authenticated requests never need CSRF — the middleware skips the check when the token arrived in the Authorization header. (Login, logout, OTP verify and the TOTP setup calls are outside the CSRF check; refresh enforces it itself for the cookie flow.)
Refresh flow
- Client hits an endpoint; access token expired →
401witherror_type: TOKEN_EXPIRED. - Client calls
POST /api/v1/auth/refresh. The browser sends therefresh_tokencookie (and must includeX-CSRF-Token); a programmatic client sends{"refresh_token":"..."}in the body (CSRF-exempt, tokens returned in the body). - On success: new cookies set (browser) or new tokens returned (body client). Retry the original request.
- On failure (reuse detected, expired, or account deactivated):
401. Redirect to login.
Reuse detection: presenting a refresh token that's already been consumed invalidates the whole token family — see Sessions.
Login endpoint
POST /api/v1/auth/login
Content-Type: application/json
{ "username": "alice", "password": "..." }
# → 200 OK (also sets access_token / refresh_token / csrf_token cookies)
{
"user": { "id": "...", "org_id": "...", "username": "alice", "auth_source": "local", ... },
"access_token": "<jwt>",
"refresh_token": "<opaque hex token>",
"token_type": "Bearer",
"expires_in": 900,
"csrf_token": "<token>"
}
The user object carries no role; call GET /auth/me for the roles. With "cookie_only": true the four token fields are omitted (the browser UI's mode). Wrong credentials → 401 {"error":"invalid username or password"}.
If the user has TOTP enrolled, login still returns 200 — but with no tokens: { "otp_required": true, "otp_setup_required": false, "otp_session_id": "<id>" }. It is not a 401. Complete it with POST /api/v1/auth/otp/verify carrying the X-OTP-Session-ID header and {"code":"123456"}, which returns the same token body. When the OTP policy requires enrolment and the user has none, otp_setup_required is true instead, and the same session id authorises POST /auth/totp/setup + /auth/totp/verify-setup.
Logout
POST /api/v1/auth/logout
Ends the sign-in session and clears all cookies. No CSRF header is needed. Every refresh token of the session the access token belongs to is revoked — whether the client keeps it in the refresh_token cookie or in its own storage — so a refresh after logout answers 401. A Bearer client may also send its refresh token in the body ({"refresh_token": "…"}); it is revoked only when it belongs to the signed-in user. Other sessions of the same user (another browser, another API client) are not affected. The access token itself stays valid until it expires (15 minutes by default) — drop it client-side.
Tokens issued before 1.7.0 carry no session; for those, logout revokes the cookie's token and the one in the body.
For an SSO account whose provider has Sign out at the identity provider too on, the answer carries redirect_url: the provider's sign-out address (OIDC end_session_endpoint, or a signed SAML LogoutRequest). Send the browser there to end the provider's session as well — the sign-in page does. See Sign-in methods → Signing out.
Who am I
GET /api/v1/auth/me
# → { "user": {...}, "roles": [...], "csrf_token": "..." } (roles = org-wide + per-project role assignments, the user's own and those it has through user groups — each of the latter carries via_group)
GET /api/v1/auth/me/profile
# → { "user": {...} } (editable via PATCH /auth/me/profile)
Both are read-only and accept either cookie or Bearer auth.
CORS
There is no CORS support at all — no allowlist setting exists, and the server sends no CORS headers. The UI and API are served from the same origin by design. A cross-origin browser app must be proxied onto the same origin (put CertAutoPilot and your app behind one reverse proxy); server-side callers are unaffected, since CORS is a browser rule.
Auth error codes
| Status | error_type | Meaning |
|---|---|---|
| 401 | TOKEN_MISSING | No access token (cookie or Bearer header). |
| 401 | TOKEN_EXPIRED | Access token expired; refresh and retry. |
| 401 | TOKEN_INVALID | Signature / format wrong. |
| 401 | TOKEN_REUSE | Refresh token already used; family revoked. |
| 401 | ACCOUNT_DEACTIVATED | The user was deactivated (refresh / OTP verify). |
| 401 | OTP_LOCKED / OTP_SESSION_EXPIRED | Too many wrong OTP codes, or the OTP session timed out — log in again. |
| 403 | — | Authenticated but role too low (insufficient role). |
| 403 | — | Cookie mutation missing / wrong X-CSRF-Token. |
| 403 | — | Licence certificate cap reached (certificate_limit_reached), or the Free plan's one-target cap on target creation (target_limit_reached). |
| 429 | — | Too many login / refresh / OTP attempts (per IP; login also per username). |
Troubleshooting
403 "CSRF" on a Bearer call
You're also sending cookies, so the middleware treats it as a cookie session. Drop the cookies — Bearer auth should be headers-only.
TOKEN_EXPIRED immediately after login
System clock skew > access token TTL (15 min). NTP the backend.
Browser CORS error from a test harness
Tests call from a different origin. There is no allowlist setting to add it to — proxy the test traffic through the same origin, or drive the API from the test runner's server side rather than the browser.
See also
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →