← Back to API Documentation Main Documentation

Authentication Flows

Created: Original date unknown
Updated: Tue 29 Jul 2025 07:36:15 CEST - Renamed from authentication-flows.md and added Jekyll front matter
Document Version: 1.1 - Updated during file structure reorganization
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, Frontend Developers, Security Engineers
Author: Paul Wisén

Plings relies on Supabase Auth and JWTs to secure the GraphQL API. The key points below are distilled from architecture/api-security-guidelines.md.

Login & Token Issuance

  1. User authenticates via email/password, magic-link or OAuth provider managed by Supabase.
  2. Supabase returns an access token (JWT) and a refresh token.
  3. The frontend stores tokens in memory (or secure storage on mobile) and attaches Authorization: Bearer <jwt> to every HTTP or WebSocket request.

Custom Claims Enrichment

An Auth webhook injects additional, namespaced claims so that Row-Level Security (RLS) can evaluate them efficiently:

{
  "role": "org_member",      // guest | org_member | manufacturer_issuer | system_owner
  "org_id": "acme-123",      // current tenant context (UUID)
  "org_role": "admin"        // member | admin | owner within the tenant
}

GraphQL Context Resolution

On each request the backend:

async def get_context(request):
    token = request.headers.get("Authorization", "").split("Bearer ")[-1]
    user  = resolve_user_from_token(token)  # Supabase helper
    return { "request": request, "user": user }

The user object is then available in every resolver for fine-grained checks.

Token Refresh

The client automatically uses Supabase’s refresh endpoint to rotate tokens before expiry. WebSocket connections include the latest token via the connectionParams payload and reconnect when refreshed.

Logout

Status: imported skeleton – expand with diagrams & edge cases (MFA, SSO) later.