Authentication and access

Bitstride supports multiple access patterns for different use cases:

Browser sessions for first-party web and console experiences
Scoped API keys for programmatic access and inference calls
OAuth2/OIDC tokens for first-party application integration

Browser auth

Browser authentication is cookie-based:

session is an opaque HTTP-only cookie
refresh_token is rotated server-side
/v1/auth/verify is the canonical session check
/v1/auth/logout ends the session
/v1/auth/refresh refreshes the current session

For local development, shared cookies are the reason the repo uses bitstride.local, app.bitstride.local, docs.bitstride.local, and api.bitstride.local.

The control plane supports first-party OAuth login flows for:

Google
GitHub

Entry points:

GET /v1/auth/login/{provider}
GET /v1/auth/callback/{provider}

MFA

Multi-factor auth is exposed in the auth surface:

POST /v1/auth/mfa/enroll
POST /v1/auth/mfa/verify
POST /v1/auth/mfa/verify-login
POST /v1/auth/mfa/disable

API keys

API keys are stored as hashed secrets and support:

Named keys
Scoped permissions
Optional expiration
Optional rate limits
Revocation
Usage tracking

Current key management routes:

GET    /v1/api_keys
POST   /v1/api_keys
PUT    /v1/api_keys/{id}
DELETE /v1/api_keys/{id}

OAuth2 and OIDC provider

Bitstride now operates as a first-party OAuth2/OIDC provider. The auth service exposes:

GET  /.well-known/openid-configuration
GET  /v1/auth/.well-known/openid-configuration
GET  /oauth2/jwks
GET  /oauth2/authorize
POST /oauth2/token
POST /oauth2/revoke
POST /oauth2/introspect
GET  /userinfo

The initial first-party OAuth clients are:

bitstride-web
bitstride-console
bitstride-cli

These clients use Authorization Code with PKCE (S256) and strict redirect URI allowlists.

Resource server model

The latest auth changes make the API and gateway behave as OAuth2 resource servers:

The control plane API validates session or bearer-based access for operator routes
The inference gateway applies route-scoped authz and rate limiting for deployment inference
Session-backed inference remains supported for first-party experiences
Scope-based authorization is enforced on all protected routes

Auth service architecture

The dedicated auth service is now the owner of browser auth, session mutation, MFA, OAuth login, and API-key lifecycle.

The API still exposes compatibility URLs for first-party callers:

/v1/auth/*
/v1/api_keys/*

Those compatibility routes are proxy shims backed by AUTH_SERVICE_URL; they no longer execute in-process auth mutations in the control-plane API outside test-only compatibility coverage.

The standalone auth service (services/auth/) handles:

Browser cookie auth and sessions
OAuth login (Google, GitHub)
MFA enrollment and verification
API key management
OAuth2/OIDC provider endpoints
Token refresh and revocation

For direct frontend usage, prefer NEXT_PUBLIC_AUTH_URL. If it is unset, first-party clients fall back to NEXT_PUBLIC_API_URL and continue through the compatibility shim.

RBAC and authorization

The auth system now includes RBAC (Role-Based Access Control) groundwork:

Auth-owned schema for roles, permissions, and user-role assignments
Scope-based authorization on protected routes
Resource server validation for both session and token-based requests

Recommendation

Use browser sessions for the console and internal first-party tools. Use scoped API keys for automation, CI, and deployment-scoped inference callers. Use OAuth2/OIDC tokens when building first-party applications that need delegated access.

Authentication and Access