API Reference
API reference — authentication
The HeyMello API uses bearer token authentication. You log in with your credentials to receive an access token, then include that token on every subsequent request.
Logging in
POST /auth/login
{
"email": "[email protected]",
"password": "your-password"
}
If MFA is not enabled, you get a token straight away:
{
"access_token": "eyJ…",
"token_type": "bearer"
}
If MFA is enabled, login responds that a second step is needed:
{ "mfa_required": true }
Then complete it with a code from your authenticator app (or a backup code):
POST /mfa/verify
{
"email": "[email protected]",
"code": "123456"
}
→ returns your access_token.
Using the token
Send the token as a bearer header on every request:
Authorization: Bearer <access_token>
Tokens expire after a set period. When a token expires, requests return 401 — simply log in again to get a new one.
MFA endpoints
| Method & Path | Purpose |
|---|---|
POST /mfa/setup | Generate a TOTP secret + QR code to scan into an authenticator app. |
POST /mfa/enable | Confirm setup with a 6-digit code; enables MFA and issues backup codes. |
POST /mfa/verify | Verify a code during login to complete authentication. |
POST /mfa/disable | Turn off MFA (password required). |
POST /mfa/backup-codes | Regenerate backup codes (invalidates old ones). |
GET /mfa/status | Check whether MFA is enabled. |
Account & password endpoints
| Method & Path | Purpose |
|---|---|
POST /external/signup | Self-service signup — creates an organization and user, sends a verification email. |
GET /auth/verify-email?token= | Verify an email address via the emailed link. |
POST /auth/resend-verification | Resend the verification email. |
POST /auth/forgot-password | Request a password-reset email. |
POST /auth/reset-password | Set a new password using the emailed token. |
POST /auth/logout | Log out. |
Notes
- Email verification is required before you can log in (outside development).
- Least privilege: new users start with the read-only role. An admin can grant more. See Team & roles.
- Keep tokens secret. Treat access tokens like passwords; never embed them in client-side code or commit them to source control.
Next: Core endpoints →