Astravera API Suite Integration

A complete guide to authenticating and building across the Astravera ecosystem.

The Architecture

The Astravera suite operates on a multi-service architecture where distinct backend APIs focus on specific domains while sharing a unified database state and Reverb real-time transport mechanism.

Hermes API (Identity Core): The foundational layer. Responsible for Authentication (Laravel Passport/Sanctum), User Management, Workspace isolation, and Invite operations.
Kairos API (Execution Core): The operational layer. Responsible for Boards, Items, Team Activity Feeds, and Project Execution. Must be used with a verified Hermes user session.
Nomia API (Completion Core): The document layer. Responsible for Secure Envelopes, Contract Signature Workflows, and immutable Completion Records.

Authentication & Authorization

Astravera utilizes Laravel Sanctum for SPA authentication and stateful sessions, and Laravel Passport for cross-service internal OAuth token validation.

1. Authenticating as a User

To interact with Kairos or Nomia, the user must first authenticate with Hermes.

Request a CSRF token: GET http://localhost:8081/sanctum/csrf-cookie
Submit credentials: POST http://localhost:8081/login with email and password
Once authenticated, Hermes sets a stateful session cookie (hermes_session). Cross-domain requests must include withCredentials: true.

Common Workflows

Bootstrapping Workspace Context

Every user belongs to one or more Workspaces. Most Kairos and Nomia endpoints automatically resolve to the active CurrentWorkspace defined on the User model. Use Hermes to manage the user's active workspace state before making execution requests against Kairos. Use the Accept: application/json header to ensure correctly formatted API validation errors.

Event Streaming via Reverb

All backend activity across Hermes, Kairos, and Nomia is broadcasted synchronously via the centralized Astravera-Reverb WebSocket server. When connecting to the public WebSocket port (default: 6001), use the shared astravera-key to subscribe to user-specific private channels for real-time item creation and signature progress updates.

Select an API from the top navigation to view interactive endpoint documentation.