doc_version: "1.0.0" last_updated: "2026-06-18" status: "Active"

bast-security-api¶

Version: 0.1.21 Module: bast_security_api Path: src/apis/security

Overview¶

Authentication and security API service with support for multiple auth providers including WorkOS, Google OAuth, and Microsoft authentication.

Features¶

Authentication Providers¶

WorkOS integration (SSO, passwordless)
Google OAuth authentication
Microsoft authentication (MSAL)
JWT token management

User Management¶

User session management
User memory/preferences storage
Token refresh
Logout handling

Endpoints¶

Authentication Endpoints¶

Endpoint	Method	Description
`/api/v1/auth/workos`	POST	WorkOS authentication
`/api/v1/auth/workos/callback`	GET	WorkOS callback
`/api/v1/auth/google`	POST	Google OAuth
`/api/v1/auth/google/callback`	GET	Google callback
`/api/v1/auth/microsoft`	POST	Microsoft auth
`/api/v1/auth/microsoft/callback`	GET	Microsoft callback
`/api/v1/auth/logout`	POST	User logout
`/api/v1/auth/refresh`	POST	Token refresh

User Memory Endpoints¶

Endpoint	Method	Description
`/api/v1/auth/memory`	GET	Get user memory
`/api/v1/auth/memory`	POST	Update user memory
`/api/v1/auth/memory`	DELETE	Clear user memory

Dependencies¶

Internal Dependencies¶

Package	Purpose
bast-api-base	Core API setup
bast-ai-mongo	User data storage
bast-ai-email	Email notifications

External Dependencies¶

Package	Purpose
workos	WorkOS SDK
google-auth	Google authentication
google-auth-oauthlib	Google OAuth flow
google-api-python-client	Google APIs
msal	Microsoft authentication

Configuration¶

Environment Variables¶

Authentication providers are configured via environment variables:

WorkOS: API key, client ID
Google OAuth: Client ID, client secret, redirect URI
Microsoft: Azure client ID, client secret, tenant ID, redirect URI
JWT: Secret key, algorithm (HS256), expiration hours

All secrets are managed via environment variables and never committed to source.

YAML Configuration¶

# resources/config/{catname}.yaml
security:
  jwt:
    algorithm: HS256
    expiration_hours: 24

  providers:
    workos:
      enabled: true
    google:
      enabled: true
    microsoft:
      enabled: true

Authentication Flows¶

OAuth Flow (Google / Microsoft)¶

Client initiates authentication via POST to provider endpoint
Server returns authorization URL
User authenticates with provider
Provider redirects to callback endpoint with authorization code
Server exchanges code for tokens
Server issues JWT access token to client

WorkOS Flow¶

Client initiates auth via POST to /api/v1/auth/workos
Server returns WorkOS authorization URL
User authenticates via WorkOS (SSO, passwordless, etc.)
WorkOS redirects to callback
Server issues JWT access token

Token Refresh¶

curl -X POST /api/v1/auth/refresh \
  -H "Authorization: Bearer $REFRESH_TOKEN"

User Memory¶

# Get memory
curl /api/v1/auth/memory \
  -H "Authorization: Bearer $TOKEN"

# Update memory
curl -X POST /api/v1/auth/memory \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preferences": {"theme": "dark", "language": "en"}}'

Security Best Practices¶

JWT tokens stored in httpOnly cookies with Secure and SameSite flags
CORS configured per-environment with explicit origin allowlists
All authentication events are logged for audit trails
Token expiration enforced server-side with configurable duration

Maintainers¶

Bast AI Team