Authentication
Every request is authenticated with a session cookie. Creating a session also returns the CSRF token and the workspaces your user can act on.
This page covers the Admin and Agent APIs, which authenticate through auth.domain.test.
Voiger does not use bearer API keys. You exchange an identity-provider token for a session, and the session cookie authenticates every call after that. Write requests additionally carry a CSRF token, and every Admin and Agent request names the workspace it applies to.
sid cookie, the x_csrf_token value, and the list of workspaces. You need all three.Create a session#
POST your auth domain and identity token. Voiger replies with Set-Cookie: sid=… and a body describing who you are.
curl -X POST https://auth.domain.test/v1/auth/session \ -H "Content-Type: application/json" \ -c cookies.txt \ -d '{ "auth": { "domain": "general", "token": "eyJhb...p5g" } }'
{ "x_csrf_token": "f3096dec-aa4d-4d1f-8b2f-e9899cfcff05", "user": { "email": "dummy@domain.com" }, "workspaces": [ { "id": "bc3c54c4-ab85-4712-b155-d3744d1b13a8", "code": "let-s-eat", "name": "Lets Eat Restaurant", "user": { "type": "agent" } } ] }
The three values you keep#
sidSet-Cookie headerCookie: sid=… on every requestx_csrf_tokenx-csrf-token header on writescodeworkspaces[].codex-workspace-code headerReading data#
A read needs the session cookie and the workspace code. x-workspace-code is required on every Admin and Agent endpoint — it selects which tenant's data you are addressing, and a session with several workspaces can address any of them.
curl https://core.domain.test/v1/admin/queues \ -H "Cookie: sid=$VOIGER_SESSION" \ -H "x-workspace-code: let-s-eat"
Writing data#
Any POST, PUT or DELETE also needs the CSRF token from the session response.
curl -X POST https://core.domain.test/v1/admin/queues \ -H "Cookie: sid=$VOIGER_SESSION" \ -H "x-workspace-code: let-s-eat" \ -H "x-csrf-token: $CSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "queue": { "name": "Sales", "status": "active" } }'
x-csrf-token on a write returns 401, the same status as an expired session — so check the header before assuming the session died.From the browser#
The cookie is set by the server, so browser clients send credentials: "include" and never touch the cookie themselves. Keep x_csrf_token in memory from the session response.
const res = await fetch("https://auth.domain.test/v1/auth/session", { method: "POST", credentials: "include", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ auth: { domain: "general", token } }), }) const { x_csrf_token, workspaces } = await res.json() const workspace = workspaces[0].code
Ending a session#
Delete Session clears the cookie server-side. The x_csrf_token dies with it.
curl -X DELETE https://auth.domain.test/v1/auth/session \ -H "Cookie: sid=$VOIGER_SESSION" \ -H "x-csrf-token: $CSRF_TOKEN"
Next: put this to work in Staffing a queue, which creates a queue and assigns agents to it end to end.