Skip to main content

Authentication Overview

DPaaS supports multiple authentication methods to secure both human and programmatic access to your data platform.

Authentication Methods​

JWT Tokens (User Authentication)​

For: Human users accessing the platform via web UI or applications

  • Short-lived access tokens (15 minutes)
  • Long-lived refresh tokens (7 days)
  • RS256 asymmetric signing
  • Account switching support
  • MFA/2FA optional

Use cases:

  • Web application login
  • Mobile app authentication
  • Interactive CLI tools
  • User-facing dashboards

Learn more about User Authentication →

HMAC Signatures (Service Account Authentication)​

For: Programmatic API access via service accounts

  • Request integrity validation
  • Replay attack protection with nonces
  • Time-window validation (5 minutes)
  • IP allowlist support

Use cases:

  • CI/CD pipelines
  • Background jobs
  • Third-party integrations
  • Server-to-server communication

Learn more about HMAC Authentication →

Authentication Flow Comparison​

FeatureJWT (Users)HMAC (Service Accounts)
Target AudienceHumansMachines/Services
Credential TypeEmail + PasswordAccess Key + Secret Key
Token Duration15 minutes (renewable)Request-based (stateless)
MFA Support✅ Yes❌ No (use IP allowlists)
Session Management✅ Yes❌ Stateless
Account Switching✅ Yes❌ Fixed account
Replay ProtectionToken expiryNonce + timestamp

Security Features​

Multi-Factor Authentication (MFA/2FA)​

Users can enable additional security:

  • TOTP (Time-based One-Time Password) - Google Authenticator, Authy
  • WebAuthn (Hardware keys) - YubiKey, TouchID, Windows Hello

Learn more about MFA →

API Key Management​

Service accounts use API keys for authentication:

  • Access key (public identifier)
  • Secret key (private, shown once)
  • Optional expiration dates
  • IP allowlist restrictions
  • Individual key revocation

Learn more about API Keys →

Session Management​

User sessions are tracked and manageable:

  • View active sessions per device
  • Remote session revocation
  • Automatic expiration after inactivity
  • Refresh token rotation

Learn more about Session Management →

JWT Token Structure​

Access tokens contain user identity and current account context:

{
  "sub": "user-john001",
  "email": "[email protected]",
  "organization_id": "org-abc123xyz",
  "organization_slug": "abc123",
  "account_id": "acc-prod001",
  "account_ids": ["acc-dev001", "acc-prod001"],
  "exp": 1696089600,
  "iat": 1696089000
}

Key Claims:

  • sub - User ID
  • account_id - Currently active account
  • account_ids - All accounts user has access to
  • organization_slug - For routing and key prefixes
  • exp - Token expiration timestamp

HMAC Request Structure​

HMAC signatures are computed from:

HMAC-SHA256(
  secret_key,
  HTTP_METHOD + "\n" +
  PATH + "\n" +
  QUERY_STRING + "\n" +
  x-date + "\n" +
  x-nonce + "\n" +
  x-content-sha256
)

Required Headers:

Authorization: HMAC sa_abc123_acc456_xyz:base64-signature
x-date: 2025-09-30T12:00:00Z
x-nonce: unique-request-id
x-content-sha256: sha256-of-request-body

Organization Context​

important

Organization context is never included in API paths. It is inferred from:

  • JWT tokens: organization_id and organization_slug claims
  • API keys: Encoded in the access key prefix (sa_{org_slug}_{account_id}_...)
  • Subdomains: Optional subdomain routing ({org_slug}.dpaas.example.com)

Public Endpoints​

Some endpoints don't require authentication:

  • GET /organizations/info - Get organization info by subdomain or slug
  • POST /authentication/login - Authenticate user
  • GET /.well-known/jwks.json - JWT public keys

All other endpoints require authentication via JWT or HMAC.

Best Practices​

✅ DO​

  • Rotate credentials regularly - API keys every 90 days, user passwords periodically
  • Use MFA for admin accounts - Extra security for privileged access
  • Store secrets securely - Use environment variables, secret managers
  • Implement token refresh - Don't re-authenticate on every token expiry
  • Use HTTPS everywhere - Never send credentials over HTTP

❌ DON'T​

  • Hardcode credentials - Always use configuration or environment variables
  • Share API keys - Issue separate keys per service/environment
  • Ignore token expiry - Implement proper refresh logic
  • Log sensitive data - Never log tokens, passwords, or secret keys
  • Reuse nonces - Generate unique nonces for every HMAC request

Next Steps​