Authentication API

AuthenticationEndpoints

Complete authentication API endpoints for user login, registration, token management, and password operations with JWT token-based authentication.

Authentication Flow

EasyAuth uses JWT tokens with secure HTTP-only cookies for session management

1. Register/Login

User provides credentials

2. Token Issue

JWT tokens stored in cookies

3. Authorized Requests

Tokens validate requests

4. Token Refresh

Automatic token renewal

API Endpoints

POST/auth/login

User Login

Authenticate a user with email and password credentials.

Parameters

Parameter	Type	Required	Description
email	string	Required	User email address
password	string	Required	User password

Responses

200Login successful

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "user_1234567890",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user",
      "created_at": "2023-01-15T10:30:00Z"
    }
  }
}

400Invalid credentials

{
  "success": false,
  "message": "Invalid email or password",
  "error": "LOGIN_FAILED"
}

POST/auth/register

User Registration

Parameters

Parameter	Type	Required	Description
email	string	Required	User email address
password	string	Required	User password (min 6 characters)
username	string	Required	Unique username
emailConfig	object	Optional	Email verification configuration

Responses

201Registration successful

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "user_1234567890",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user",
      "email_verified": false,
      "created_at": "2023-01-15T10:30:00Z"
    }
  }
}

400Registration failed

{
  "success": false,
  "message": "Email already exists",
  "error": "REGISTRATION_FAILED"
}

POST/auth/refresh

Refresh Token

Refresh an expired access token using a valid refresh token.

Responses

200Token refreshed successfully

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "user": {
      "id": "user_1234567890",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user"
    }
  }
}

401Invalid refresh token

{
  "success": false,
  "message": "Invalid or expired refresh token",
  "error": "INVALID_TOKEN"
}

POST/auth/logout

User Logout

Logout user and invalidate all tokens (access and refresh).

Responses

200Logout successful

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

POST/auth/reset-password

Reset Password

Send password reset email to user.

Parameters

Parameter	Type	Required	Description
email	string	Required	User email address

Responses

200Reset email sent

{
  "success": true,
  "message": "Password reset email sent"
}

404User not found

{
  "success": false,
  "message": "User not found",
  "error": "USER_NOT_FOUND"
}

POST/auth/verify-token

Verify Token

Verify if the current access token is valid.

Responses

200Token is valid

{
  "success": true,
  "message": "Token is valid",
  "data": {
    "user": {
      "id": "user_1234567890",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user"
    }
  }
}

401Invalid token

{
  "success": false,
  "message": "Invalid or expired token",
  "error": "INVALID_TOKEN"
}

cURL Examples

Ready-to-use cURL commands for testing authentication endpoints

Authentication Examples

# Login Example
curl -X POST https://easyauth-server.vercel.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

# Registration Example  
curl -X POST https://easyauth-server.vercel.app/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "securePassword123",
    "username": "newuser"
  }'

# Token Refresh Example
curl -X POST https://easyauth-server.vercel.app/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -H "Cookie: refresh_token=your_refresh_token_here"

# Logout Example
curl -X POST https://easyauth-server.vercel.app/api/v1/auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token_here"

Important Notes

Token Storage: Access and refresh tokens are automatically stored in secure HTTP-only cookies.

Token Expiration: Access tokens expire after 15 minutes. Use the refresh endpoint or let the SDK handle automatic renewal.

CORS: All authentication endpoints support CORS for browser-based applications.

Rate Limiting: Authentication endpoints are rate-limited to 5 requests per 15 minutes per IP address.