mcias-junie/docs/api.org

MCIAS API Documentation

• MCIAS API Documentation
  • Overview
  • API Endpoints
    • Authentication
      • Password-based Authentication
      • Token-based Authentication
    • Database Credentials
    • TOTP Authentication
  • Error Handling
  • Authentication Flow

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:

{
    "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):

{
    "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:

{
    "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):

{
    "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: 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):

{
    "host": "database_host",
    "port": 5432,
    "name": "database_name",
    "user": "database_user",
    "password": "database_password"
}

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:

{
    "version": "v1",
    "login": {
        "user": "username",
        "password": "secret_password",
        "totp": "123456"
    }
}

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):

{
    "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, password, or TOTP code
• 500 Internal Server Error: Server-side error

Error Handling

All error responses follow a standard format:

{
    "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
   • 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