Skip to content

Login

Method

REST method is adopted.

HTTP Method

POST: Authentication

Naming Convention

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

Request and Response

Headers

Meta information is set in HTTP headers rather than in the response body.

Request Headers

  • Content-Type: application/json

Response Headers

  • Content-Type: application/json

Authentication

URI

/api/v1/auth/login

Request Body

Request body is JSON. 

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

Validation Rules

Field Rule
email Required. Must be a valid email format.
password Required. Minimum 8 characters, at least 1 uppercase, 1 lowercase, and 1 number.

Response (200 OK)

Response is JSON. 

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "Admin User",
    "cognito_sub": "1111-aaaa-2222-bbbb",
    "email": "admin@example.com",
    "role": {
      "id": 1,
      "name": "admin"
    }
  }
}

Authentication

This endpoint does not require authentication.

Exception Handling

Exception handling status codes are as follows.

Description Status Code Status Name
Invalid request body or validation error 400 Bad Request
Invalid email or password 401 Unauthorized
Internal server error 500 Internal Server Error

Process Flow

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Hono Router
    participant Validate as Zod Validation
    participant Service as Auth Service
    participant Cognito as AWS Cognito
    participant DB as PostgreSQL Database

    Client->>API: POST /api/v1/auth/login
    API->>Validate: Validate email & password
    Validate-->>API: Validation passed

    API->>Service: login(email, password, ip, user_agent)
    Service->>Cognito: initiateAuth(email, password)

    alt Authentication Success
        Cognito-->>Service: Access Token + Cognito Sub
        Service->>DB: Find admin by cognito_sub
        DB-->>Service: Admin record
        Service->>DB: Create session (hashed token, ip, user_agent, expires_at)
        DB-->>Service: Session created
        Service-->>API: { token, user }
        API-->>Client: 200 OK { token, user }
    else Authentication Failed
        Cognito-->>Service: NotAuthorizedException
        Service-->>API: throw UnauthorizedError
        API-->>Client: 401 Unauthorized
    end

Routes Layer

API routing is performed here. Validates request body using Zod schema, extracts client IP and user agent, then delegates to the auth service.

Source: src/routes/v1/auth.ts:27

Services Layer

This section describes business logic. It authenticates against AWS Cognito, looks up the admin user, creates a session record in the database, and returns the JWT token with user info.

Source: src/services/auth.ts

Repositories Layer

This section describes access to databases and external services. It handles admin lookups by Cognito sub and session creation with SHA-256 token hashing.

Source: src/repositories/

Security

  • Client IP address and user agent are logged for audit purposes
  • Session tokens are stored as SHA-256 hashes in the database
  • Failed login attempts are logged with request context
  • Password complexity enforced via both Zod validation and Cognito policies