vicket
Get started
API / Nº 04

API authentication

The Vicket API exposes two authentication flavors. Each is bound to a different audience and a different surface of the API. Mixing them is rejected at the edge.

Session cookie (dashboard)

The hosted agent dashboard authenticates users with a session cookie issued after a WorkOS-backed login (email + password or Google/GitHub). After a successful login the user is redirected to /v1/auth/callback?code=... which exchanges the code, sets a vicket_session cookie (HttpOnly, Secure, SameSite=Lax), and redirects into the dashboard.

The cookie carries no permissions itself: it identifies the user, and every request is authorized against the roles-and-permissions matrix on the server.

You do not call session-authenticated endpoints from your code. They power the dashboard at vicket.app.

Site key (pk_...)

The public endpoints under /support/v1/... accept a site-scoped publishable key in the X-Vicket-Key header:

GET /support/v1/help/articles HTTP/1.1
Host: api.vicket.app
X-Vicket-Key: pk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

The key is validated and resolved on every request: the server hashes the presented value and looks that hash up to find the site. There is no site identifier in the URL; the key IS the identity, and everything it returns or creates is scoped to its site.

The key is publishable: it is designed to ship in the browser. Two server-side guards make that safe: the per-site origin allowlist below, and per-site rate limits. See api-keys for creation, rotation, and format.

CORS

Public endpoints respond with Access-Control-Allow-Origin reflecting the request Origin, only if that origin is in the site's allowlist. Anything else gets no CORS header at all (browsers refuse the response).

The allowlist is configured per site in the dashboard under Websites, your site, Origins. Wildcards are not supported: list every exact origin (scheme + host + port).

{
  "origins": [
    "https://app.acme.com",
    "https://staging.acme.com",
    "http://localhost:3000"
  ]
}

Errors

Authentication failures use a stable error shape:

{
  "error": {
    "code": "auth.unauthorized",
    "message": "Invalid or missing credentials."
  }
}

Common codes: auth.unauthorized (missing or invalid credentials), auth.forbidden (authenticated but not allowed).

Next