Skip to main content
Video tutorial · 1:28

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}` }}).

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:

CookiePathFlagsPurpose
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/authHttpOnly, SameSite=Lax, Secure*Refresh token (7 days default).
csrf_token/SameSite=Lax, Secure*, readable by JSCSRF 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​

  1. Client hits an endpoint; access token expired → 401 with error_type: TOKEN_EXPIRED.
  2. Client calls POST /api/v1/auth/refresh. The browser sends the refresh_token cookie (and must include X-CSRF-Token); a programmatic client sends {"refresh_token":"..."} in the body (CSRF-exempt, tokens returned in the body).
  3. On success: new cookies set (browser) or new tokens returned (body client). Retry the original request.
  4. 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​

Statuserror_typeMeaning
401TOKEN_MISSINGNo access token (cookie or Bearer header).
401TOKEN_EXPIREDAccess token expired; refresh and retry.
401TOKEN_INVALIDSignature / format wrong.
401TOKEN_REUSERefresh token already used; family revoked.
401ACCOUNT_DEACTIVATEDThe user was deactivated (refresh / OTP verify).
401OTP_LOCKED / OTP_SESSION_EXPIREDToo 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.

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 →

Automate Certificates with the REST APIYouTube ↗