Authentication Endpoints

These endpoints handle user registration, login, logout, and session refresh.

Note

Authentication endpoints are primarily used by the MoMail dashboard. API key authentication is preferred for programmatic access.

Register a New User

Create a new user account.

POST /auth/register

Request Body

{
  "email": "user@example.com",
  "password": "secure_password_123",
  "name": "John Doe"
}

Parameters

Field	Type	Required	Description
email	string	Yes	Valid email address
password	string	Yes	Minimum 8 characters
name	string	Yes	User’s full name

Response

{
  "success": true,
  "data": {
    "userId": "user_123456",
    "email": "user@example.com",
    "name": "John Doe",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Errors

Status	Code	Description
400	VALIDATION_ERROR	Invalid email or password too short
409	CONFLICT	Email already registered

Login

Authenticate and receive access credentials.

POST /auth/login

Request Body

{
  "email": "user@example.com",
  "password": "secure_password_123"
}

Parameters

Field	Type	Required	Description
email	string	Yes	Registered email address
password	string	Yes	User’s password

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g...",
    "expiresIn": 3600,
    "user": {
      "userId": "user_123456",
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

Errors

Status	Code	Description
401	UNAUTHORIZED	Invalid email or password

Logout

Invalidate the current session.

POST /auth/logout

Headers

Authorization: Bearer {access_token}

Response

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

Refresh Token

Obtain a new access token using a refresh token.

POST /auth/refresh

Request Body

{
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Errors

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired refresh token

Code Examples

cURL

# Register
curl -X POST https://api.momail.io/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password_123",
    "name": "John Doe"
  }'

# Login
curl -X POST https://api.momail.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password_123"
  }'

JavaScript

// Register
const registerResponse = await fetch('https://api.momail.io/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'secure_password_123',
    name: 'John Doe'
  })
});

const { data } = await registerResponse.json();
console.log('User ID:', data.userId);

// Login
const loginResponse = await fetch('https://api.momail.io/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'secure_password_123'
  })
});

const { data: loginData } = await loginResponse.json();
localStorage.setItem('accessToken', loginData.accessToken);

Python

import requests

# Register
response = requests.post(
    'https://api.momail.io/v1/auth/register',
    json={
        'email': 'user@example.com',
        'password': 'secure_password_123',
        'name': 'John Doe'
    }
)
print(f"User created: {response.json()['data']['userId']}")

# Login
login_response = requests.post(
    'https://api.momail.io/v1/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'secure_password_123'
    }
)
token = login_response.json()['data']['accessToken']