Login

Method

REST method is adopted.

HTTP Method

POST: User login

Naming Convention

To unify the naming of query parameters and nodes and improve readability, snake_case is used for URIs and JSON nodes in requests.

Request and Response

Headers

Meta information is set in HTTP headers, not in the response body.

Request Headers

• Content-Type
• Accept
• Accept-language

Response Headers

• Content-Type

Login

URI

POST /v1/auth/login

Request Body

The request body is JSON.

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

Request Parameters

Name	Type	Required	Description
email	string	Required	Email address (valid email format)
password	string	Required	Password (minimum 8 characters)

Response

The response is JSON.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid",
    "cognitoSub": "cognito-sub-uuid",
    "organizationId": "org-uuid",
    "name": "John Doe",
    "createdAt": 1234567890000,
    "updatedAt": 1234567890000
  }
}

Response Fields

Name	Type	Description
token	string	JWT access token
user	object	User information
user.id	string	User UUID
user.cognitoSub	string	Cognito identifier
user.organizationId	string	Organization UUID
user.name	string	User name
user.createdAt	number	Creation timestamp (epoch milliseconds)
user.updatedAt	number	Update timestamp (epoch milliseconds)

Authentication

This endpoint does not require authentication.

Error Handling

The status codes for error handling are as follows.

Description	Status Code	Status Name
Invalid email format	400	Bad Request
Invalid credentials	401	Unauthorized
Internal server error	500	Internal Server Error

Processing Flow

1. Extract and validate email/password from request body
2. Retrieve IP address and user agent for session tracking
3. Authenticate with AWS Cognito
4. Create session record in the database
5. Return JWT access token and user information

Detailed Flowchart

flowchart TD
    Start([POST /v1/auth/login]) --> Route[Route Handler]
    Route --> ValidateInput[Input Validation<br/>Zod Schema]

    ValidateInput --> ValidEmail{email validation}
    ValidEmail -->|NG| Err400[400 Bad Request]
    ValidEmail -->|OK| ValidPass{password validation<br/>min 8 chars}

    ValidPass -->|NG| Err400
    ValidPass -->|OK| ExtractMeta[Extract Metadata]

    ExtractMeta --> GetIP[Get IP Address<br/>X-Forwarded-For]
    ExtractMeta --> GetUA[Get User-Agent]

    GetIP --> Cognito[AWS Cognito Auth]
    GetUA --> Cognito

    Cognito --> CognitoAuth{Auth successful?}
    CognitoAuth -->|NG| Err401[401 Unauthorized<br/>Invalid credentials]
    CognitoAuth -->|OK| GetTokens[Get JWT Tokens]

    GetTokens --> CreateSession[Create Session DB Record<br/>sessionId, IP, UA]

    CreateSession --> GetUser[Get User Info<br/>cognitoSub]

    GetUser --> UserExists{User exists?}
    UserExists -->|No| Err401
    UserExists -->|Yes| Success[200 OK<br/>token + user]

Security

• Log IP address and user agent for security monitoring
• Log failed login attempts
• Rate limiting prevents brute force attacks