Skip to content

Create Admin

Method

REST method is adopted.

HTTP Method

POST: Create a new admin account

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

  • Authorization: Bearer <access_token>
  • Content-Type: application/json

Response Headers

  • Content-Type: application/json

Create Admin

URI

/api/v1/admins

Request Body

Request body is JSON. 

{
  "email": "admin@example.com",
  "temporaryPassword": "TempPass123",
  "name": "New Admin",
  "roleId": 1
}

Validation Rules

Field Rule
email Required. Must be a valid email format.
temporaryPassword Required. Minimum 8 characters. Cognito will force a password change on first login.
name Required. 1-255 characters.
roleId Required. Must be a positive integer referencing an existing role.

Response (201 Created)

Response is JSON. 

{
  "id": 2,
  "cognitoSub": "3333-cccc-4444-dddd",
  "roleId": 1,
  "name": "New Admin",
  "createdAt": 1640995200000,
  "updatedAt": 1640995200000,
  "createdBy": "1111-aaaa-2222-bbbb",
  "updatedBy": "1111-aaaa-2222-bbbb",
  "deletedAt": null,
  "deletedBy": null,
  "role": {
    "id": 1,
    "name": "admin"
  }
}

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. A valid Bearer token is required in the Authorization header.

Exception Handling

Exception handling status codes are as follows.

Description Status Code Status Name
Missing or invalid token 401 Unauthorized
Role not found 404 Not Found
Duplicate admin or Cognito conflict 409 Conflict
Internal server error 500 Internal Server Error

Process Flow

Sequence Diagram

sequenceDiagram
    participant Client
    participant Middleware as Protected Route Middleware
    participant API as Hono Router
    participant Service as Admin Service
    participant Cognito as Admin Cognito Pool
    participant DB as PostgreSQL Database

    Client->>Middleware: POST /api/v1/admins
    Middleware->>Middleware: Verify JWT & session

    alt Token Valid
        Middleware-->>API: Auth info (sub)
        API->>Service: create({ email, tempPassword, name, roleId, actorSub })
        Service->>DB: Find role by ID

        alt Role Found
            Service->>Cognito: adminCreateUserWithTempPassword
            Cognito-->>Service: User created
            Service->>Cognito: getCognitoSubByEmail
            Cognito-->>Service: cognitoSub

            alt DB Insert Success
                Service->>DB: Create admin record
                DB-->>Service: Admin record with role
                Service-->>API: Admin with relations
                API-->>Client: 201 Created
            else DB Insert Failed
                Service->>Cognito: adminDeleteUser (rollback)
                Service-->>API: throw Error
                API-->>Client: 500 Internal Server Error
            end
        else Role Not Found
            DB-->>Service: null
            Service-->>API: throw NotFoundError
            API-->>Client: 404 Not Found
        end
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes Layer

API routing is performed here. The protectedRoute middleware validates the JWT token. The handler validates the request body via Zod schema, extracts the actor's Cognito sub, and delegates to the admin service.

Source: apps/admin/src/routes/v1/admin.ts

Services Layer

This section describes business logic. It validates the role exists, creates the admin user in the admin Cognito pool with a temporary password, resolves the Cognito sub, and creates the database record. If the DB insert fails, it rolls back by deleting the Cognito user.

Source: apps/admin/src/services/admin.ts

Repositories Layer

This section describes access to databases and external services. It handles role lookup, Cognito admin user creation/sub-resolution/deletion, and admin record creation.

Source: apps/admin/src/repositories/admin.ts / apps/admin/src/repositories/cognito-pool.ts

Security

  • Token validated by protectedRoute middleware before handler execution
  • Uses the admin Cognito pool (separate from the app user pool)
  • Cognito rollback on DB failure prevents orphaned Cognito users
  • Temporary password forces admin to change password on first login