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.org
+++ b/docs/api.org
@@ -0,0 +1,128 @@
+#+title: MCIAS API Documentation
+#+created: <2025-05-09 Fri 13:42>
+
+* 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*:
+#+begin_src json
+{
+    "version": "v1",
+    "login": {
+        "user": "username",
+        "password": "secret_password"
+    }
+}
+#+end_src
+
+*Required Fields*:
+- =version=: Must be "v1"
+- =login.user=: Username
+- =login.password=: User's password
+
+*Response Format* (Success - 200 OK):
+#+begin_src json
+{
+    "token": "authentication_token",
+    "expires": 1621234567
+}
+#+end_src
+
+*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*:
+#+begin_src json
+{
+    "version": "v1",
+    "login": {
+        "user": "username",
+        "token": "existing_token"
+    }
+}
+#+end_src
+
+*Required Fields*:
+- =version=: Must be "v1"
+- =login.user=: Username
+- =login.token=: Previously issued authentication token
+
+*Response Format* (Success - 200 OK):
+#+begin_src json
+{
+    "token": "new_authentication_token",
+    "expires": 1621234567
+}
+#+end_src
+
+*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:
+
+#+begin_src json
+{
+    "error": "Error message describing the issue"
+}
+#+end_src
+
+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