Accounts and businesses
Magnum uses Better Auth and PostgreSQL for account identity. Each account has one business; the internal Workspace identifier remains in API routes to scope resources, not to offer a multi-business account.
Identity
Sign-in, email verification, recovery and sessions use /api/auth/*. Registration remains disabled until an authorized email transport is configured, a real delivery is verified and AUTH_ALLOW_SIGNUP is enabled. No default password or account is created.
A successful verification creates a verified session. A browser success query parameter does not establish verification. Recovery tokens expire, are single-use and revoke prior sessions after a successful reset.
Business ownership
The server enforces one business per account and associates integrations, API keys, checkout sessions, payments and settings with that business. Supplying another business identifier never grants access. Existing plural route names are retained for API compatibility.
GET /v1/account/workspaces: the account's business membership, if configured.POST /v1/account/workspaces: create the account's business; a second business is rejected.GET /v1/account/workspaces/:workspaceId/api-keys: read key metadata.POSTto the same path: create a scoped key with an authorized role.DELETE /v1/account/workspaces/:workspaceId/api-keys/:keyId: revoke an owned key.
Session mutations require the exact Magnum origin. Business authorization is checked on the server for every read and change. Invitations, role administration and multi-business account switching are not offered by this release.
Receiving configuration
The business configures its fixed receiving addresses in Settings. GET and PUT /v1/console/workspaces/:workspaceId/settlement read and update the authorized business configuration. Each destination has a network and matching asset. The payer cannot select or replace the beneficiary in the checkout.
The 4P credential is managed only by the Magnum operator on the backend. Businesses do not provide, read or replace this global credential. This technical arrangement does not establish permission to process multiple businesses under one provider account; live use still requires explicit 4P approval of the applicable model.
Receiving settings API
PUT /v1/console/workspaces/:workspaceId/settlement replaces the complete destination list. Its body is { "destinations": [{ "network": "ethereum", "address": "YOUR_VERIFIED_MAINNET_ADDRESS" }] }; replace the address placeholder with an address you control before submitting. Send destinations: [] only when intentionally clearing all unused destinations.
Each entry accepts network and address only. The server derives the asset from the network catalog, validates mainnet address syntax/checksums where applicable and permits one address per network. The operation requires a verified owner/admin session no older than 15 minutes and the exact application origin. It stores addresses encrypted and records an audit event.
GET returns the authorized business's destinations with network, asset and address, plus availableNetworks, configuredNetworks, status and liveEnabled. Availability in this technical catalog is not provider entitlement. A saved address does not prove control of that address or commercial approval; verify both before any future live use.
A duplicate network returns DUPLICATE_NETWORK; an invalid address returns INVALID_SETTLEMENT_ADDRESS. Removing a destination required by an active live integration returns SETTLEMENT_IN_USE. Creating or editing a live integration without all required destinations returns SETTLEMENT_REQUIRED; live checkout creation still remains blocked afterward.
GET /v1/console/workspaces/:workspaceId/provider returns sanitized operator-integration metadata only. Legacy PUT and DELETE return 410 CENTRALIZED_PROVIDER_CONFIG and never save business-supplied provider keys.