128 lines
3.1 KiB
Org Mode
128 lines
3.1 KiB
Org Mode
#+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 |