Build

Keep machine and user access separate

Use scoped API keys for service requests and cookie sessions with CSRF protection for signed-in management.

Prerequisites

Choose the credential from the operation, not from convenience. Service code needs an organization API key with the required scope. Organization management needs a verified signed-in user with access to that organization.

Working flow

Mode	Use it for	Credential and request rule
API key	Server-side event ingestion and supported API-key reads	`Authorization: Bearer useeventstack_…`; no browser CSRF token
User session	Contract, API-key, integration, and other dashboard management	`HttpOnly` session cookie; unsafe methods also echo the readable CSRF cookie in `x-useeventstack-csrf`

API-key ingestion

POST /events requires events:write or *. The server uses the API key’s organization and environment, even though the event envelope contains an organization identifier.

curl "$USEEVENTSTACK_API_BASE/events"   --request POST   --header "Authorization: Bearer $USEEVENTSTACK_API_KEY"   --header 'Content-Type: application/json'   --header 'X-UseEventStack-Environment: sandbox'   --data "{
    "type": "deployment.completed",
    "organization_id": "$USEEVENTSTACK_ORGANIZATION_ID",
    "metadata": {
      "schema_version": 1,
      "source": "ci.release",
      "trace_depth": 0,
      "environment": "sandbox"
    },
    "payload": {
      "service": "api",
      "version": "1.0.0",
      "environment": "sandbox",
      "status": "healthy"
    }
  }"

User-session management

Login and signup set useeventstack_session as an HttpOnly cookie and useeventstack_csrf as a readable signed cookie. Browser callers send credentials: 'include'. For POST, PUT, and DELETE management requests, copy the CSRF cookie value into x-useeventstack-csrf.

The signed-in dashboard performs this exchange for routes such as contract registration. An API key does not become a user session and cannot be used for session-only management routes.

Expected response

A successful API-key event write returns the stored event inside an API response:

{
  "event": { "id": "…", "type": "deployment.completed", "payload": { "…": "…" } },
  "api_key_id": "…",
  "published": true
}

A successful login establishes cookies; the JSON body does not return a readable session token. Session management responses depend on the selected management route.

Failure diagnosis

authentication_required: check that the Bearer key is present or that the browser included its session cookie.
csrf_verification_failed: on an unsafe session request, send the CSRF header and cookie from the same current session.
email_verification_required: verify the signed-in account before contract registration.
Forbidden API-key request: check the required scope and ensure the request environment matches the key.
Forbidden management request: use a user session with membership and the role required by that route, not an API key.

Authorization is per route

Authorization varies by route and role. Treat the dashboard flow and inspected route behavior as the current boundary; do not infer access to one management route from access to another.