Authentication

API key management, permissions, and security best practices.

API Key Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sv_live_your_api_key

API Key format

Grosend API keys follow the format:

SMTP Authentication

For SMTP, use your email address as the username and your generated SMTP key as the password. Generate an SMTP key in Settings → SMTP.

Username: your-email@example.com
Password: your-generated-smtp-key

Session Authentication

The web dashboard uses session-based authentication via NextAuth. Login at send.grosend.com/app.

Two-Factor Authentication (2FA)

2FA is required for session-based access (dashboard). After login, you'll be prompted to set up TOTP (e.g., Google Authenticator, Authy).

// Enable 2FA
POST /api/v1/account/2fa/setup
// Returns: { secret, otpauthUrl }

// Verify setup with TOTP code
POST /api/v1/account/2fa/verify
{"code": "123456"}
// Returns: { enabled: true, backupCodes: [...] }

// Disable 2FA (requires TOTP or backup code)
POST /api/v1/account/2fa/disable
{"code": "123456"}

// Regenerate backup codes
POST /api/v1/account/2fa/backup
{"code": "123456"}

Security best practices

• Never expose API keys in client-side code or public repos
• Rotate API keys regularly
• Use separate keys for development and production
• Monitor API key usage in the dashboard
• Enable 2FA on your account