API Integration & Third-Party Tooling

This guide provides an overview for developers looking to build integrations, CLI utilities, or third-party client applications for the platform.

1. Interactive API Documentation (Swagger UI)

For an interactive, real-time reference of all available REST endpoints, request schemas, and response types, consult the built-in Swagger UI.

Local Development: http://localhost:7777/swagger-ui/
Production / Remote: https://<your-domain>/api/swagger-ui/

The Swagger UI allows you to inspect model schemas, test queries directly against a running server instance, and inspect expected status codes (e.g., 401 Unauthorized, 412 Precondition Failed, 422 Unprocessable Entity).

2. Official Rust SDK Crate

If you are developing third-party tools or microservices in Rust, you can use the official SDK crate rather than implementing raw HTTP logic.

Installation

Add the SDK dependency to your Cargo.toml:

[dependencies]
openfab-sdk = "0.1" # Adjust crate name/version as appropriate
tokio = { version = "1", features = ["full"] }

Quick Example

use openfab_sdk::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client with base URL and Bearer Access Token
    let client = Client::new("https://api.yourdomain.com", "your_bearer_token_here")?;

    // Perform operations via the client SDK
    let user = client.users().me().await?;
    println!("Authenticated as: {}", user.email);

    Ok(())
}

3. Authentication & Bearer Tokens

All protected API endpoints require authentication using standard HTTP Bearer Tokens in the Authorization header.

Header Format

Authorization: Bearer <your_access_token>

Obtaining an Access Token (web UI only)

OIDC / SSO Authorization Flow: Complete the OpenID Connect web flow to acquire an ID/Access token pair.
Account Activation / Local Login: Submit user credentials or complete account activation via the /accounts/activate endpoint to acquire a session token.

Security Guidelines

Token Storage: Store tokens securely (e.g., using OS keyring services for CLI tools, or secure, HTTP-only cookies for web applications).
Transit Security: All production API endpoints strictly enforce HTTPS/TLS. Non-TLS requests will be rejected.

4. API Architecture & Key Components

The platform API is structured around clear domain boundaries to simplify building custom tools:

Primary Domain Modules

Identity & Accounts (/accounts, /auth)
- Handles user registration, OIDC account linking, account activation, and credential management.
- Enforces strict identity collision checks (returns 409 Conflict on email collision rather than silent linking). (For security reasons this will be excluded from the standard REST API until further notice.)

Error Handling & Status Code Taxonomy

The API adheres to a strict error taxonomy to simplify programmatic client logic:

Status Code	Meaning	Common Cause
`401 Unauthorized`	Authentication Failure	Missing, invalid, or expired Bearer token.
`403 Forbidden`	Permission Denied	Authenticated user lacks specific DB/RBAC permissions.
`409 Conflict`	Identity Collision	Email already exists under another account provider.
`412 Precondition Failed`	State Requirement	Account activation required (`is_active == false`).
`422 Unprocessable Entity`	Validation Failure	Invalid request parameters or form fields.

5. Building Third-Party Tooling

When creating custom integrations (such as CLI tools, desktop wrappers using Slint/Tauri, or web widgets):

Use the OpenAPI Spec: You can download the raw OpenAPI JSON/YAML definition directly from /api/openapi.json to auto-generate client bindings for other languages (Python, Go, TypeScript).
Handle Precondition Errors: Always check for 412 Precondition Failed responses to gracefully prompt users to complete email activation or administrator setup.
Respect Rate Limits: Ensure long-running scripts handle exponential backoff on retries.

Keyboard shortcuts

OpenFab