Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.digifist.com/llms.txt

Use this file to discover all available pages before exploring further.

Galantis uses three distinct authentication mechanisms: Shopify OAuth for store access, Meta OAuth for WhatsApp Business Account access, and Inertia.js session-based authentication for the merchant dashboard. Each mechanism is scoped to a specific integration or access path and stores credentials encrypted per tenant.

​
What this covers

  • Shopify OAuth token exchange and usage
  • Meta OAuth token exchange, storage, and scope
  • Internal dashboard session authentication
  • Multi-tenant credential isolation
  • Token security model

​
Shopify OAuth

​
Token exchange

Shopify authentication is initiated during app installation. The process uses ShopifyTokenExchangeService: 
Merchant installs Galantis from Shopify App Store
  → Shopify redirects to Galantis OAuth callback with authorization code
  → ShopifyTokenExchangeService exchanges code for access token
  → Access token stored encrypted per tenant
  → Tenant workspace created and associated with the Shopify store
The resulting access token is a Shopify Admin API access token scoped to the permissions granted during installation. It does not expire on a schedule — it remains valid until the app is uninstalled or the merchant revokes it from Shopify Admin.

​
Usage

All Shopify Admin API calls are made by ShopifySdkService using the tenant’s encrypted access token. ShopifySdkService handles:
  • Customer data fetching and webhook subscription management
  • Order data retrieval for automation context
  • Abandoned checkout polling via the Shopify Admin GraphQL API
  • App subscription management for billing
ShopifySdkService resolves the correct tenant’s access token from the encrypted store and injects it into every API request. No access token is ever passed in application-level code — ShopifySdkService abstracts the credential management entirely.

​
Token lifecycle

EventEffect on token
App installedToken issued and stored encrypted
App uninstalledapp/uninstalled webhook received; tenant deactivated; token no longer used
Token manually revoked in ShopifyAPI calls begin failing; requires reinstallation to restore
Shopify store plan changeToken typically unaffected — scope changes only occur on permission re-grant

​
Meta OAuth

​
Token exchange

Meta authentication is initiated from within the Galantis dashboard when a merchant connects their WhatsApp Business Account. The process uses WhatsappConnectionController: 
Merchant clicks Connect WhatsApp in Settings
  → WhatsappConnectionController@prepareToConnect retrieves Meta OAuth URL
  → Merchant authorizes in Meta Business Manager
  → Meta redirects back with authorization code
  → WhatsappConnectionController@connect exchanges code for access token
  → Access token stored encrypted per tenant

​
Token scope and usage

The Meta access token grants Galantis access to:
  • The WhatsApp Business Account’s registered phone numbers
  • The Message API for sending messages via the selected phone number
  • The Template API for creating, submitting, and reading template status
  • The Media Upload API for uploading template header assets
A separate optional Meta Catalog access token can be connected for catalog operations. This token is scoped specifically to:
  • Reading from and writing to the merchant’s Meta Catalog via the Catalog API
All Meta API calls are made by MetaGraphClient, which resolves and injects the correct tenant’s encrypted token per request.

​
Token expiry

Unlike Shopify tokens, Meta access tokens are subject to expiry. Long-lived tokens have a defined validity window. They can also be revoked if the authorizing Meta user changes their credentials or revokes the app authorization in Meta’s settings. When a Meta token expires or is revoked:
  • All Meta API calls for that tenant fail
  • Messages stop sending
  • Template status stops updating
  • Catalog sync fails (if the catalog token is affected)
Recovery requires the merchant to re-authorize via the OAuth flow in Settings → WhatsApp Connection. See Connecting WABA for the reconnection steps.

​
Multiple phone numbers

When a workspace has multiple phone numbers, each number is associated with the same WABA access token — the token is scoped to the WABA, not to individual phone numbers. API calls specify the phone_id in the endpoint path to route messages through the correct number.

​
Internal dashboard authentication

The Galantis merchant dashboard uses Inertia.js with session-based authentication. Agents and team members authenticate with email and password credentials. Sessions are managed server-side by Laravel’s session system. Multi-tenant routing resolves the correct tenant workspace from the request context (subdomain or request header) before session authentication runs. A valid session in Tenant A does not grant access to Tenant B — tenant isolation is enforced at the database layer before any application logic evaluates permissions. Role-based access control is enforced by Spatie Laravel Permission. Every authenticated request is validated against the user’s role and the specific permission required for the requested action (TenantPermissionsEnum). See Inbox — Roles & Permissions for the role and permission reference.

​
Token security model

All access tokens — Shopify and Meta — are stored encrypted in the per-tenant PostgreSQL schema. The encryption uses application-level encryption rather than database-level encryption, meaning tokens are encrypted before being written to the database and decrypted only when needed for API calls. Key security properties:
  • No access token is logged in plaintext in application logs
  • No access token is returned in API responses to the merchant dashboard — credentials are write-only from the merchant’s perspective
  • Tenant schema isolation means a compromised query in one tenant’s context cannot read another tenant’s tokens
  • ShopifySdkService and MetaGraphClient are the only application components that decrypt and use tokens — the decryption is not accessible from merchant-facing code paths