mcias/docs/api.org

#+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*: =GET /v1/database/credentials=
*Description*: Retrieves database credentials for authorized users.
*Request Parameters*:
- =username=: Username of the authenticated user
*Headers*:
- =Authorization=: Bearer token for authentication
*Response Format* (Success - 200 OK):
#+begin_src json
{
    "host": "database_host",
    "port": 5432,
    "name": "database_name",
    "user": "database_user",
    "password": "database_password"
}
#+end_src
*Error Responses*:
- 400 Bad Request: Invalid request format or missing required parameters
- 401 Unauthorized: Invalid or expired token
- 403 Forbidden: Insufficient permissions to access database credentials
- 500 Internal Server Error: Server-side error

*** TOTP Authentication
*Endpoint*: =POST /v1/login/totp=
*Description*: Authenticates a user using TOTP (Time-based One-Time Password) in addition to username and password.
*Request Format*:
#+begin_src json
{
    "version": "v1",
    "login": {
        "user": "username",
        "password": "secret_password",
        "totp": "123456"
    }
}
#+end_src
*Required Fields*:
- =version=: Must be "v1"
- =login.user=: Username
- =login.password=: User's password
- =login.totp=: 6-digit TOTP code from authenticator app
*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, password, or TOTP code
- 500 Internal Server Error: Server-side error

** 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
   - If TOTP is enabled for the user, authentication with password alone will fail

2. *TOTP Authentication*:
   - For users with TOTP enabled, client sends username, password, and TOTP code to =/v1/login/totp=
   - Server validates all credentials and returns a token

3. *Subsequent Requests*:
   - Client uses the token for authentication by sending it to =/v1/login/token=
   - Server validates the token and issues a new token

4. *Token Expiration*:
   - Tokens expire after 24 hours
   - Clients should request a new token before expiration

5. *Database Credential Access*:
   - Client sends a GET request to =/v1/database/credentials= with the token in the Authorization header
   - Server validates the token and returns the database credentials if the user has sufficient permissions