Skip to main content
Use an API key in the Authorization header. 
Authorization: Bearer lodger_sk_...
API keys can be restricted by scope, project, and allowed event action.

​
Scopes

  • events:write allows POST /v1/events and POST /v1/consents.
  • events:read allows retained-event queries and minting scoped receipt, policy, activity, and evidence-package tokens.
Public receipt verification and public published policy reads do not require dashboard or API-key authentication. Private project receipts and policies require a dashboard session, a read-capable API key, or a scoped token. Activity trails always require a signed activity token and the project must allow activity links. Dashboard access exchanges the Ave ID token for an HttpOnly Lodger session cookie. Business workspaces use Ave organization context: Lodger stores product data under the Ave org_id, and every workspace request checks the verified organization context instead of a Lodger-owned membership table. Use Ave’s normal access token to list business workspaces before requesting organization context: 
import { listAveWorkspaceOrganizations } from "@ave-id/sdk/client"

const organizations = await listAveWorkspaceOrganizations(
  { clientId: aveClientId },
  tokens.access_token
)
Start the Ave PKCE flow with organizationId when a user chooses a business workspace. Lodger requires the session org_id to match the requested workspace ID, and it displays the Ave organization name from the organization-context token. read can use read routes, sign or approve can record event and consent evidence, and manage_org can manage workspace settings, projects, keys, billing, and policy changes. If a signed-in user creates a workspace from Lodger, Lodger calls Ave’s workspace creation API only after the UI says the workspace will be Ave-managed: 
import { createAveWorkspaceOrganization } from "@ave-id/sdk/client"

const organization = await createAveWorkspaceOrganization(
  { clientId: aveClientId },
  tokens.access_token,
  {
    name: "Example Co",
    userConfirmedAveWorkspaceCreation: true,
  }
)
Use organization.id as the next organizationId and send the user through organization-context sign-in before opening the workspace. Dashboard workspaces are Ave organizations. A normal Ave identity session can list or create organizations, but workspace actions require a fresh organization-context sign-in whose org_id matches the workspace. Workspace access lists are an extra Lodger-side filter after Ave membership. Use Ave handles or email addresses in whitelist and blacklist rules. Set LODGER_SESSION_SECRET to at least 32 characters before deploying dashboard auth. If you use a custom Ave app, set LODGER_AVE_AUDIENCE or AVE_CLIENT_ID to the token audience. Private deployments can set LODGER_REQUIRE_ALLOWED_IDENTITIES=1 with LODGER_ALLOWED_IDENTITIES to restrict who may sign in. Activity, receipt, policy, and evidence tokens are signed with LODGER_SESSION_SECRET. Activity tokens are scoped to one workspace, one project, and one subject. Receipt tokens are scoped to one receipt. Policy tokens are scoped to one project. Evidence tokens are scoped to one evidence package and can verify private receipts included in that package. Browser links keep scoped tokens in the URL fragment, and API clients should send them as Authorization: Bearer.

​
Idempotency

Event and consent writes require Idempotency-Key with at least 12 characters. Use a stable key for retryable operations: 
member_removed_{member_id}_{request_id}
If a request is retried with the same key, Lodger returns the existing receipt instead of appending a duplicate record.

​
Provenance headers

Send these headers from server-side integrations when available:
  • X-Lodger-Environment
  • X-Lodger-Server
  • X-Request-Id
  • X-Session-Id
  • X-Trace-Id
  • traceparent
Lodger also records received time, auth kind, API key identity, IP, and user agent when available.