Login

Authenticate a user with email and password

POST /api/auth/login

Login

cURL

curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>"
}
'

200

{
  "400": {},
  "401": {},
  "message": "<string>",
  "token": "<string>",
  "user": {
    "id": "<string>",
    "email": "<string>",
    "name": "<string>",
    "role": "<string>",
    "walletAddress": {}
  }
}

Overview

Authenticate a user with their email and password. This endpoint validates credentials, generates new JWT tokens, and returns user information.

Request Body

email · string · required

User’s email address. Must be a valid email format.

password · string · required

User’s password.

Response

message · string

Success message confirming login.

token · string

JWT access token valid for 15 minutes. Include this token in the Authorization header as Bearer {token} for authenticated requests.

user · object

Authenticated user information.

Show user properties

id · string

Unique user identifier (UUID).

email · string

User’s email address.

name · string

User’s full name.

role · string

User’s role (USER or ORGANIZER).

walletAddress · string | null

User’s Ethereum wallet address if available.

Authentication Tokens

Access Token

• Type: JWT (JSON Web Token)
• Expiration: 15 minutes
• Payload: Contains userId, email, and role
• Usage: Include in Authorization: Bearer {token} header

Refresh Token

• Type: JWT (JSON Web Token)
• Expiration: 7 days
• Storage: HttpOnly cookie named refreshToken
• Usage: Automatically sent with requests to refresh access token

Example Request

cURL

curl -X POST https://api.gatepass.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "SecurePass123"
  }'

Example Response

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20iLCJyb2xlIjoiVVNFUiIsImlhdCI6MTcwOTczNjAwMCwiZXhwIjoxNzA5NzM2OTAwfQ...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[e-mail]",
    "name": "John Doe",
    "role": "USER",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}

Error Responses

400 · Bad Request

Invalid email format or missing password.

{
  "error": "Invalid email format"
}

401 · Unauthorized

Invalid credentials (email or password is incorrect).

{
  "error": "Invalid email or password"
}

Token Refresh

When the access token expires (after 15 minutes), use the refresh token to obtain a new access token:

cURL

curl -X POST https://api.gatepass.com/api/auth/refresh-token \
  -H "Cookie: refreshToken={refresh_token}"

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Access Token

Include the access token in the Authorization header for all authenticated requests:

cURL

curl -X GET https://api.gatepass.com/api/events \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Security Features

• Password Hashing: Passwords are hashed using bcrypt with 12 rounds
• Email Normalization: Email addresses are normalized before comparison
• HttpOnly Cookies: Refresh tokens stored in HttpOnly cookies prevent XSS attacks
• Secure Cookies: In production, cookies are only sent over HTTPS
• SameSite Protection: Cookies use SameSite: strict to prevent CSRF attacks

Session Management

The refresh token is stored in the database and can be invalidated by:

• Calling the /api/auth/logout endpoint
• Token expiration (7 days)
• Manual token revocation