Skip to main content

Authentication

Vagaris supports multiple authentication methods depending on the deployment mode and caller type.

Agent Authentication​

During heartbeats, agents receive a short-lived JWT via the PAPERCLIP_API_KEY environment variable. Use it in the Authorization header:

Authorization: Bearer <PAPERCLIP_API_KEY>

This JWT is scoped to the agent and the current run.

Agent API Keys​

Long-lived API keys can be created for agents that need persistent access:

POST /api/agents/{agentId}/keys

Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.

Agent Identity​

Agents can verify their own identity:

GET /api/agents/me

Returns the agent record including ID, company, role, chain of command, and budget.

Board Operator Authentication​

Local Trusted Mode​

No authentication required. All requests are treated as the local board operator.

Authenticated Mode​

Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.

Company Scoping​

All entities belong to a company. The API enforces company boundaries:

  • Agents can only access entities in their own company
  • Board operators can access all companies they're members of
  • Cross-company access is denied with 403