Skip to content

Create Organization

Method

REST method is adopted.

HTTP Method

POST: Create a new organization

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 Organization

URI

/api/v1/organizations

Request Body

Request body is JSON. 

{
  "name": "New Organization"
}

Validation Rules

Field Rule
name Required. Must be a string between 1 and 255 characters.

Response (201 Created)

Response is JSON. 

{
  "id": 1,
  "name": "New Organization",
  "createdAt": 1640995200000,
  "updatedAt": 1640995200000,
  "createdBy": "1111-aaaa-2222-bbbb",
  "updatedBy": "1111-aaaa-2222-bbbb",
  "deletedAt": null,
  "deletedBy": null
}

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
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 Organization Service
    participant Repository as Organization Repository
    participant DB as PostgreSQL Database

    Client->>Middleware: POST /api/v1/organizations
    Middleware->>Middleware: Extract Bearer token
    Middleware->>Middleware: Verify JWT & session

    alt Token Valid
        Middleware-->>API: Auth info (sub, adminId)
        API->>API: Validate request body (Zod)
        API->>Service: create(name, adminId)
        Service->>Repository: create({ name, createdBy, updatedBy })
        Repository->>DB: INSERT INTO organizations
        DB-->>Repository: Inserted row
        Repository-->>Service: Created organization
        Service-->>API: Organization data
        API-->>Client: 201 Created { id, name, ... }
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes Layer

API routing is performed here. The protectedRoute middleware validates the JWT token and session before the handler executes. The handler validates the request body using a Zod schema and delegates to the organization service.

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

Services Layer

This section describes business logic. It receives the validated organization name and the authenticated admin's ID, then delegates to the repository to create a new organization record with audit fields populated.

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

Repositories Layer

This section describes access to databases and external services. It inserts a new row into the organizations table with the provided name and audit metadata (createdBy, updatedBy), returning the created record.

Source: apps/admin/src/repositories/organization.ts

Security

  • Token validated by protectedRoute middleware before handler execution
  • Session existence verified via verifySession
  • Request body validated with Zod schema to prevent malformed input