Get started/Authentication
App
Get started

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.

The Console API authenticates separately. It runs on its own host and its session body takes only a token — no domain, and no workspaces come back. Treat it as a distinct flow rather than a variation of this one.

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.

Three things come out of a single call to Create Session: the 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.

bash
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"
    }
  }'
json
{
  "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#

Value
Where it comes from
How you send it
sid
the Set-Cookie header
Cookie: sid=… on every request
x_csrf_token
the response body
x-csrf-token header on writes
workspace code
workspaces[].code
x-workspace-code header

Reading 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.

bash
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.

bash
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" } }'
Omitting 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.

js
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.

bash
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.

ESC