Authentication

How requests to the GuideLab API are authenticated.

Almost every GuideLab endpoint requires an authenticated request. The API accepts two authentication schemes; pick whichever fits your client.

Session cookie (web app)

The GuideLab web app authenticates with Better Auth. After signing in, the browser holds a session cookie named __Secure-guidelab-prod.session_token, which is sent automatically with every request to api.guidelab.co.

This is the scheme used by the first‑party web app — you generally don't manage it yourself; it is set by the sign‑in flow and refreshed by the auth layer.

GET /orders HTTP/1.1
Host: api.guidelab.co
Cookie: __Secure-guidelab-prod.session_token=<session-token>

Native device credential (desktop / programmatic clients)

Non-browser clients authenticate with a versioned GuideLab device credential issued by POST /auth/device/v1/sign-in. Send that credential in the Authorization header. Better Auth browser session tokens are cookie-only and are not accepted as bearer credentials.

GET /orders HTTP/1.1
Host: api.guidelab.co
Authorization: Bearer gl_device_v1_<redacted>

curl "https://api.guidelab.co/orders" \
  -H "Authorization: Bearer gl_device_v1_<redacted>"

Organization context

GuideLab is multi‑tenant. An authenticated session is bound to a single organization (a lab or a clinic) and a role within it (owner or staff). Endpoints automatically operate on that organization's data, and some are restricted:

• By organization type — e.g. lab‑only or clinic‑only endpoints.
• By role — e.g. owner‑only settings endpoints.

A request that is authenticated but lacks the required type or role receives a 403 response.

Unauthenticated requests

Requests without a valid session cookie or native device credential receive a 401 Unauthorized. A small number of endpoints (such as inbound webhooks and health checks) are public and do not require authentication.