Skip to content

🔐 Sanctum Token Flow¶

%%{init: {'themeVariables': {'fontSize': '17px'}, 'sequence': {'useMaxWidth': true, 'actorFontSize': 17, 'messageFontSize': 16, 'noteFontSize': 15, 'mirrorActors': false}}}%%
sequenceDiagram
    participant User as Authenticated User
    participant Console as Token Issuer (Web/API)
    participant Sanctum
    participant Client as Headless Client
    participant API as RawDigs API

    User->>Console: POST /user/api-tokens (name, scopes, device metadata)
    Console->>Sanctum: Issue token for user with scopes
    Sanctum-->>User: Return plain-text token (once)
    User->>Client: Configure Authorization: Bearer <token> + metadata
    Client->>API: Request protected endpoint (Authorization header)
    API->>Sanctum: Validate token signature + scopes
    Sanctum-->>API: Token valid, attach user + scope claims
    API-->>Client: Authorized data response (scoped payload)

Client Profiles & Scopes¶

Client Typical scope bundle Notes
mobile_app (iOS/Android/iPad) catalog.read, orders.read, notifications.read Uses device-specific token created from the user settings screen; devices can be individually revoked.
creator_cli (RawDigs CLI / CI) catalog.write, media.upload, orders.read Service accounts for automated publishing or QA ingest pipelines.
label_integration (3rd-party ERP/royalty tools) orders.read, payouts.export, artists.manage Issued by organization owners; requires acceptance of data-sharing terms.
partner_storefront (embedded storefronts) catalog.read, products.read Read-only tokens used for signed storefronts or Jamstack builds.

Scopes map back to Spatie permissions: the Sanctum ability must also be allowed by the user’s org/artist role or the request is denied.

Flow Details¶

  1. Token creation – A signed-in user (or org owner acting in the Filament dashboard) names the token, selects scopes, and optionally tags the client type/device. We store hashed token + metadata in Accounts.
  2. Distribution – Plain-text secret is shown once; clients store it securely (mobile keychain, CI secret store, partner vault).
  3. Request lifecycle – Clients call api.rawdigs.com with Authorization: Bearer <token>. Middleware swaps to the issuing user, applies the active organization/team context if supplied (X-Organization-ID header), and checks scopes before hitting controllers.
  4. Policy enforcement – Controllers still run standard Spatie gates/policies; tokens cannot bypass role restrictions even if a scope exists.
  5. Audit trail – Each use emits ApiTokenUsed with client metadata, route, and organization context, feeding Analytics + anomaly detection.

Operational Guidelines¶

  • Rotate long-lived tokens quarterly; mobile clients refresh during app updates or account reset.
  • Organization owners can revoke partner tokens immediately; downstream services receive 401 and should request a new secret through the partner workflow.
  • Pair tokens with IP allowlists or signed webhook secrets when integrating with external infrastructures.
  • For end-user mobile apps, prompt re-authentication if the server flags token abuse (e.g., excessive failures, unexpected geography).

Use token auth for any RawDigs client that can’t rely on first-party cookies—mobile apps, hardware kiosks, external services, or automated tooling—while keeping the same cooperative governance and security controls in place.