Skip to main content

Authentication & Access Control

Authentication and authorization are enforced before any GGNomad operation runs: every caller is authenticated, every field is permission-checked, and every query is scoped to the caller's workspace. This is the same identity layer used across the Burdenoff platform, so GGNomad is enterprise-ready from day one.

How callers authenticate​

Single sign-on (OIDC) Travelers, hosts, and operators sign in through single sign-on:

  • OpenID Connect for interactive web sign-in
  • OAuth 2.0 for service and API access
  • OAuth device-code for terminal clients (roadmap surfaces)
  • Enterprise identity-provider integration (for example Okta, Azure AD)

API keys Automation and integrations use workspace-scoped credentials issued from the developer portal:

  • Bearer-token authentication
  • Scoped to a single workspace
  • Rotatable and revocable

Access control framework​

Role-based access control (RBAC) Every GGNomad operation is permission-gated:

  • One identity can hold multiple roles — traveler, host/operator, administrator
  • Each role grants a scoped set of ggnomad:* permissions
  • Every query and mutation declares the permission it requires, and that permission is checked before the operation runs

Workspace scoping Authorization is bounded by workspace, not just role:

  • The workspace comes from your authenticated session, not a client argument
  • Every read and write is filtered to that workspace
  • An id from one workspace never resolves in another (returns NOT_FOUND)
  • Audit fields (createdBy, onBehalfOf, updatedBy) are stamped on writes

Self vs. shared resources​

Access to "your own" data is scoped to the signed-in identity:

  • A traveler sees their own bookings, favorites, and trips
  • A host sees the listings and booking queue they own
  • An administrator's marketplace-wide view is granted by an explicit admin role
  • Being signed in is never enough on its own — "my" data is always filtered to the calling identity

API security​

Protect every integration call:

  • Bearer-token (OAuth / API key) authentication on every request
  • Permissions checked before the operation runs
  • Rate limiting and quota enforcement per billing plan
  • Request validation with typed error codes (FORBIDDEN, WORKSPACE_REQUIRED)

Best practices​

Follow these guidelines:

  1. Request least-privilege permissions for each integration
  2. Use separate credentials per integration so they can be rotated
  3. Treat FORBIDDEN and WORKSPACE_REQUIRED as expected, handled cases
  4. Never assume an id resolves outside its workspace
  5. Audit role assignments and watch the activity log

Getting started​

Set up secure access:

  • Sign in via SSO (travelers, hosts, operators)
  • Issue a scoped credential for integrations from the developer portal
  • Confirm your token's permissions with a read query
  • Verify cross-workspace isolation in a development workspace

For details on the API surface, see the API Reference; for the broader posture, see the Security Overview.