mcias/docs/api.md

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. This endpoint does not require TOTP verification, even if TOTP is enabled for the user.

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,
    "totp_enabled": true
}

Response Fields:

• token: Authentication token to be used for subsequent requests
• expires: Unix timestamp when the token expires
• totp_enabled: Boolean indicating whether TOTP is enabled for the user

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

TOTP Verification

Endpoint: POST /v1/login/totp

Description: Verifies a TOTP code for a user and issues a token upon successful verification. This endpoint is used as a separate flow from password authentication.

Request Format:

{
    "version": "v1",
    "username": "username",
    "totp_code": "123456"
}

Required Fields:

• version: Must be "v1"
• username: Username
• totp_code: Time-based One-Time Password code

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, missing required fields, or TOTP not enabled for user
• 401 Unauthorized: Invalid TOTP code
• 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:

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

Password Authentication Flow

1. Initial Authentication:

   • Client sends username and password to /v1/login/password
   • Server validates credentials and returns a token
   • The response includes a totp_enabled flag indicating whether TOTP is enabled for the user

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

TOTP Authentication Flow

1. TOTP Verification (separate from password authentication):
   • Client sends username and TOTP code to /v1/login/totp
   • Server validates the TOTP code and returns a token if valid

Token Management

1. Token Expiration:
   • Tokens expire after 24 hours
   • Clients should request a new token before expiration

Multi-Factor Authentication

For users with TOTP enabled, a complete multi-factor authentication flow would involve:

1. Authenticate with username and password using /v1/login/password
2. Check the totp_enabled flag in the response
3. If TOTP is enabled, prompt the user for their TOTP code
4. Verify the TOTP code using /v1/login/totp to get a second token
5. Use either token for subsequent requests (both are valid)