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.

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

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