Authentication

Purpose: Defines how users and services prove their identity to the platform and how sessions and API keys are managed.

• Doc type: Reference
• What you'll find here:
  • Authentication methods and their current activation status
  • Session management (cookies, expiration, binding)
  • API key format, scoping, and lifecycle
  • Passkey / WebAuthn authentication
  • Key management tiers (database, HSM, external custody)
• Related:
  • Authorization
  • Wallet Verification
  • Identity and Compliance
  • Signing Flow

Authentication methods

The platform uses Better Auth for identity management. The table below shows each supported method and whether it is currently active in the codebase.

Better Auth supports LDAP, OAuth 2.0/OIDC, and SAML 2.0 via installable plugins. Enabling these requires adding the corresponding Better Auth plugin to the auth configuration -- it is not a configuration-only change.

The installed Better Auth plugins are: passkey, admin, apiKey, walletPincode, walletTwoFactor, walletSecretCodes, twoFactor, customSession, organization, and openAPI.

Session authentication

Browser-based clients authenticate using HTTP-only session cookies managed by Better Auth. Key properties:

• HTTP-only cookies -- prevent client-side script access to session tokens
• Secure flag -- cookies transmit only over HTTPS
• SameSite attribute -- protects against cross-site request forgery
• Expiration -- sessions expire after 7 days, with a 24-hour refresh window
• Cookie cache -- enabled with a 10-minute max age to reduce database lookups
• Session binding -- each session associates with a user identity and active organization for complete audit trails

Session tokens bind to user identity. Every authentication event is logged with timestamp, method, and result.

Passkey authentication

Passkeys provide passwordless authentication using the WebAuthn standard. Hardware security keys and platform authenticators (Face ID, Touch ID, Windows Hello) eliminate password-related vulnerabilities.

Benefits:

• Phishing resistance -- passkeys are cryptographically bound to the origin domain
• No shared secrets -- nothing to steal from the server
• Biometric verification -- on supported devices, authentication requires a biometric or device PIN

API key authentication

Machine-to-machine integrations authenticate with API keys. Keys follow a predictable format for easy identification in logs and configuration.

Key scoping

API keys support scoped permissions that limit access to specific procedure namespaces. A key created for reporting cannot execute token operations. This follows the principle of least privilege -- each integration receives only the permissions it requires. Permissions inherit from the creating user's role (admin, owner, or member).

Key lifecycle

Keys can be created, rotated, and revoked through the console or API. Revoked keys immediately lose access. Optional expiration can be configured per key with no minimum constraint.

Key management architecture

The platform implements a three-tier key management system for blockchain signing keys:

Tier 1: Database-managed keys

Keys are encrypted and stored in the platform database. Fastest onboarding with minimal infrastructure. Suitable for development, proof-of-concept, and non-custodial scenarios.

Tier 2: Hardware security modules

Production deployments integrate with HSMs for HSM-backed key protection. Keys never leave the HSM boundary -- all signing operations execute within the secure enclave. Satisfies regulatory requirements for financial institutions.

Tier 3: External custody integration

For institutions with existing custody infrastructure, the platform delegates key management to external providers (Fireblocks, DFNS). The platform initiates signing requests; the custody solution handles key storage, access controls, and audit trails.

Organizations select their tier based on security requirements and regulatory obligations. Mixed deployments -- HSM for treasury operations, database keys for automated processes -- are supported.

Security design principles

• Layered verification: Identity authentication plus wallet verification ensure compromised credentials alone cannot execute transactions. API key sessions skip wallet verification by design — the key itself is a scoped, rate-limited credential that serves as the authorization factor for machine-to-machine use
• Fail secure: Invalid authentication, expired sessions, and missing permissions result in denied access
• Audit completeness: Every authentication event logs with timestamp, method, and result; failed attempts trigger configurable alerting
• Standard protocols: TOTP (RFC 6238), WebAuthn, and HTTP-only session cookies provide well-understood, audited primitives