Authentication

DonutMe supports three authentication methods: session cookies (for browser-based access), API keys (for server-to-server integration), and OAuth 2.1 access tokens (for third-party apps).

Session Authentication

Browser-based dashboard access uses the better-auth.session_token cookie, set after login and sent automatically by the browser. The API client issues requests with credentials: include so the cookie travels with each call — there is no Authorization header for session auth.

API Key Authentication

API keys enable server-to-server integration without user sessions. Generate keys from Account → API Keys in the dashboard. Pass the key as a Bearer token:

curl -H "Authorization: Bearer dm_your_key_here" \
  https://api.donutme.xyz/api/v1/projects/{projectId}/transactions

Key Format

API keys are issued as dm_ followed by a random string (e.g. dm_4a2b9fc8e1d3f7...). The full key is shown only once at creation; only a short hint is stored afterward. There are no separate live/test key prefixes — a key's environment is determined by the resources it accesses.

OAuth 2.1 Authentication

Third-party apps authenticate with an opaque OAuth 2.1 access token, prefixed dm_at_, also passed as a Bearer token:

curl -H "Authorization: Bearer dm_at_your_access_token" \
  https://api.donutme.xyz/api/v1/projects/{projectId}/transactions

API Key Scopes

Each API key can be restricted to specific scopes:

Note: Scopes are enforced fail-closed. A key with no scopes (scopes: []) is denied on any scoped endpoint — it grants no access. Issue the admin superscope for full access, but prefer the minimum required scopes in production.

Key Management

• Keys are shown only once at creation — store securely
• Revoke compromised keys immediately from the dashboard
• Use the minimum scopes required for your integration
• Rotate keys periodically as a security best practice

Login Methods

Session Lifecycle

1. Login → Sets the better-auth.session_token cookie
2. Use session → Cookie is sent automatically with each request
3. Refresh → Sessions auto-refresh before expiry
4. Logout → Invalidates the session and clears the cookie

Passkey Registration

Users can register passkeys for passwordless login:

1. Navigate to Account Settings → Security
2. Click Add Passkey
3. Follow your device's biometric/PIN prompt
4. Passkey is registered and can be used for future logins

Roles & Permissions

System Roles

Project Roles

Permissions are enforced using CASL on both frontend and backend.