Auth & keys

Fivexer has three credential planes. Using the right one for the right call keeps your integration simple and least-privileged.

All three send the credential the same way — Authorization: Bearer <credential> — and every SDK does it for you.

Workspace plane (sk_ keys)

Server-to-server integrations use a workspace API key:

• sk_test_... — sandbox workspace; safe to embed in CI and local dev.
• sk_live_... — production workspace; treat as a secret.

Pass the key to the SDK constructor:

python
from fivexer import Fivexer
client = Fivexer(base_url="https://api.fivexer.com", api_key="sk_test_...")

Every workspace-plane response parses X-Quota-* headers onto client.quota.

This is the only plane that can create tasks and workers, edit skills and workflows, or read decisions. It is a server credential — never ship it to a browser or a mobile app.

Worker plane (wt_ tokens)

A worker-facing UI logs in with POST /v1/worker-auth/login (or worker.login() in the SDK) using a workspace ID, worker ID, and PIN. The response contains a wt_... session token scoped to that single worker.

Use the worker client to:

• view the worker's own queue and task detail
• accept, reject, and complete assigned tasks
• start and end breaks, and read today's metrics
• set availability, change the PIN, and manage the worker's own skills
• register devices and Web Push subscriptions

python
from fivexer import FivexerWorker, WorkerLogin

worker = FivexerWorker(base_url="https://api.fivexer.com")
worker.login(WorkerLogin(workspace_id="ws_1", worker_id="agent_1", pin="4821"))
worker.accept(worker.queue().task_ids[0])

A worker session can be renewed with worker.refresh() while it is still valid.

Supervisor plane (sv_ tokens)

A supervisor is a crew lead who watches and unblocks work rather than doing it. The session is redeemed from a single-use link — there is no password and no PIN:

python
from fivexer import FivexerSupervisor, AcceptSupervisorInvite

sv = FivexerSupervisor(base_url="https://api.fivexer.com")
session = sv.accept_invite(AcceptSupervisorInvite(token="…from the ?token= of the link"))

overview = sv.overview()          # counts, crew (busiest first), and parked work in one call
sv.assign(overview.parked[0].id, overview.crew[0].worker_id)

Use the supervisor client to:

• read overview() — counts, crew, and parked work in a single round trip
• unpark() a stalled task, set_priority(), or assign() it to a specific crew member
• set_availability() for a crew member, optionally releasing their pending backlog
• subscribe to Web Push

See the supervisor plane for what a supervisor can and cannot reach.

Two details that differ from the worker plane and are easy to trip over:

• SupervisorSession.expiresAt is epoch-milliseconds, not the worker plane's ISO-8601 string. The two planes genuinely differ on the wire and the clients mirror that.
• There is no supervisor refresh. Once a session expires it can only be replaced by a new link. The clients deliberately have no recovery path, because inventing one would hide that.

Key rotation

You can create and revoke workspace keys from the console. Rotating a key does not affect in-flight tasks, worker sessions, or supervisor sessions.

logout() on either session plane revokes that session immediately. Supervisor logout also drops that supervisor's push subscriptions server-side — a handed-over phone must stop buzzing with another crew's work.