docs: generate README

README.md

@@ -1,2 +1,201 @@
-# identity-management
+# Identity Management API
 
+A high-level overview of a RESTful API for managing individual customers, their online accounts, and authenticated sessions. The API follows the JSON:API specification (`application/vnd.api+json`) for all request and response payloads.
+
+---
+
+## Base URL
+
+```
+http://localhost:8080/v1
+```
+
+---
+
+## Resources Overview
+
+| Resource                 | Description                                           |
+| ------------------------ | ----------------------------------------------------- |
+| `/individualCustomers`   | Manage individual customer records                    |
+| `/onlineAccounts`        | Manage online account credentials and associations    |
+| `/authenticatedSessions` | Create and manage authenticated sessions for accounts |
+
+---
+
+## Content-Type Requirements
+
+All **POST** and **PATCH** requests must include:
+
+```
+Content-Type: application/vnd.api+json
+```
+
+---
+
+# Individual Customers
+
+Operations under `/individualCustomers` allow clients to create, retrieve, update, and delete customer profiles.
+
+## Create Individual Customer
+
+**POST** `/individualCustomers`
+
+Example request:
+
+```json
+{
+  "data": {
+    "type": "individualCustomer",
+    "attributes": {
+      "firstName": "Jane",
+      "lastName": "Smith",
+      "emailAddress": "jane.smith@example.com"
+    }
+  }
+}
+```
+
+## Retrieve Customer
+
+**GET** `/individualCustomers/{customerId}`
+
+Example response:
+
+```json
+{
+  "data": {
+    "type": "individualCustomer",
+    "id": "12345",
+    "attributes": {
+      "firstName": "Jane",
+      "lastName": "Smith",
+      "emailAddress": "jane.smith@example.com"
+    }
+  }
+}
+```
+
+## Update Customer
+
+**PATCH** `/individualCustomers/{customerId}`
+
+Example request:
+
+```json
+{
+  "data": {
+    "type": "individualCustomer",
+    "id": "12345",
+    "attributes": {
+      "emailAddress": "new.email@example.com"
+    }
+  }
+}
+```
+
+## Delete Customer
+
+**DELETE** `/individualCustomers/{customerId}`
+
+---
+
+# Online Accounts
+
+Represents login-capable accounts tied to customers.
+
+## Create Online Account
+
+**POST** `/onlineAccounts`
+
+Example request:
+
+```json
+{
+  "data": {
+    "type": "onlineAccount",
+    "attributes": {
+      "username": "jsmith",
+      "password": "MyPassword123"
+    },
+    "relationships": {
+      "individualCustomer": {
+        "data": { "type": "individualCustomer", "id": "12345" }
+      }
+    }
+  }
+}
+```
+
+## Retrieve Online Account
+
+**GET** `/onlineAccounts/{accountId}`
+
+## Update Online Account Credentials
+
+**PATCH** `/onlineAccounts/{accountId}`
+
+Example:
+
+```json
+{
+  "data": {
+    "type": "onlineAccount",
+    "id": "acct-789",
+    "attributes": {
+      "password": "NewSecurePassword456"
+    }
+  }
+}
+```
+
+---
+
+# Authenticated Sessions
+
+Used to authenticate an online account and generate a session token.
+
+## Create Authenticated Session
+
+**POST** `/authenticatedSessions`
+
+Example request:
+
+```json
+{
+  "data": {
+    "type": "authenticatedSession",
+    "attributes": {
+      "username": "jsmith",
+      "password": "MyPassword123"
+    }
+  }
+}
+```
+
+Example response:
+
+```json
+{
+  "data": {
+    "type": "authenticatedSession",
+    "id": "session-001",
+    "attributes": {
+      "issuedAt": "2025-01-01T12:00:00Z",
+      "expiresAt": "2025-01-01T14:00:00Z",
+      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+    }
+  }
+}
+```
+
+---
+
+# License
+
+Specify license information here.
+
+---
+
+# Acknowledgments
+
+Document inspirations, contributors, or tools used in the API’s development.