Core implementation written with Junie.

2025-06-06 10:15:49 -07:00
parent 0ef669352f
commit e22c12fd39
28 changed files with 2597 additions and 24 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,125 @@
+# MCIAS API Documentation
+
+## Overview
+
+MCIAS (Metacircular Identity and Access System) provides identity and authentication services across metacircular projects. This document describes the REST API endpoints, request/response formats, and error handling.
+
+## API Endpoints
+
+### Authentication
+
+#### Password-based Authentication
+
+**Endpoint**: `POST /v1/login/password`
+
+**Description**: Authenticates a user using username and password credentials.
+
+**Request Format**:
+```json
+{
+    "version": "v1",
+    "login": {
+        "user": "username",
+        "password": "secret_password"
+    }
+}
+```
+
+**Required Fields**:
+- `version`: Must be "v1"
+- `login.user`: Username
+- `login.password`: User's password
+
+**Response Format** (Success - 200 OK):
+```json
+{
+    "token": "authentication_token",
+    "expires": 1621234567
+}
+```
+
+**Response Fields**:
+- `token`: Authentication token to be used for subsequent requests
+- `expires`: Unix timestamp when the token expires
+
+**Error Responses**:
+- 400 Bad Request: Invalid request format or missing required fields
+- 401 Unauthorized: Invalid username or password
+- 500 Internal Server Error: Server-side error
+
+#### Token-based Authentication
+
+**Endpoint**: `POST /v1/login/token`
+
+**Description**: Authenticates a user using a previously issued token.
+
+**Request Format**:
+```json
+{
+    "version": "v1",
+    "login": {
+        "user": "username",
+        "token": "existing_token"
+    }
+}
+```
+
+**Required Fields**:
+- `version`: Must be "v1"
+- `login.user`: Username
+- `login.token`: Previously issued authentication token
+
+**Response Format** (Success - 200 OK):
+```json
+{
+    "token": "new_authentication_token",
+    "expires": 1621234567
+}
+```
+
+**Response Fields**:
+- `token`: New authentication token to be used for subsequent requests
+- `expires`: Unix timestamp when the token expires
+
+**Error Responses**:
+- 400 Bad Request: Invalid request format or missing required fields
+- 401 Unauthorized: Invalid or expired token
+- 500 Internal Server Error: Server-side error
+
+### Database Credentials
+
+**Endpoint**: `/v1/credentials/database` (Not yet implemented)
+
+**Description**: Retrieves database credentials for authorized users.
+
+## Error Handling
+
+All error responses follow a standard format:
+
+```json
+{
+    "error": "Error message describing the issue"
+}
+```
+
+Common HTTP status codes:
+- 200 OK: Request successful
+- 400 Bad Request: Invalid request format or parameters
+- 401 Unauthorized: Authentication failed
+- 403 Forbidden: Insufficient permissions
+- 404 Not Found: Resource not found
+- 500 Internal Server Error: Server-side error
+
+## Authentication Flow
+
+1. **Initial Authentication**:
+   - Client sends username and password to `/v1/login/password`
+   - Server validates credentials and returns a token
+
+2. **Subsequent Requests**:
+   - Client uses the token for authentication by sending it to `/v1/login/token`
+   - Server validates the token and issues a new token
+
+3. **Token Expiration**:
+   - Tokens expire after 24 hours
+   - Clients should request a new token before expiration