Skip to content

API Overview

OpenASA API is organized by runtime modules so UI apps and agent callers can use the same integration boundaries.

Each public module now has its own directory, and each endpoint is documented on its own page.

Base URL

  • Production base URL: https://api.openasa.com/

All documented paths in this section are relative to that base URL.

Module Map

  • Agreement: list/detail/version/tags/validation and comments.
  • Catalog: service/flow/plugin list/detail/comments.
  • My resources (/me): authenticated create/update/delete for service/flow and image upload.
  • Auth: email login, profile, totp, ssh keys, and third-party OAuth login helpers.
  • OAuth Provider: OpenASA provider endpoints (authorize, token, userinfo, jwks, revoke).
  • CLI Auth: challenge/device flow endpoints for CLI callers.
  • Geo/System: geo helper endpoints.

Auth Boundaries

  • Public read APIs: most list/detail endpoints in agreement/catalog/geo/system.
  • Session-required APIs:
  • /me/*
  • write comment endpoints (POST .../comments)
  • /auth/me, /auth/totp/*, /auth/ssh-keys*
  • /cli/device/approve

Auth is cookie-session based for browser flows. Keep Allow-Credentials compatible CORS settings when integrating cross-origin frontends.

Auth Modes

Mode Credential shape Best for Start here
Browser session Session cookie Web app login and third-party OAuth redirect helper flows Auth Module
Email token pair accessToken + refreshToken Programmatic callers that need token-based auth Auth Module
CLI device/challenge CLI-approved session flow asactl and terminal-based login CLI Module

GET /auth/userinfo returns the current authenticated account context for the active auth flow.

GET /auth/me reads or updates the profile record of the signed-in user.

Error and Status Model

  • Typical status set: 200, 400, 401, 404, 500, and 502 (IP locate upstream failure).
  • Error payload shape commonly includes:
  • error: machine-oriented reason
  • message: human-readable detail

Treat exact fields as contract-defined by OpenAPI for each endpoint.

Rate-Limited Areas

  • Email login/auth request & verify endpoints
  • CLI challenge/device endpoints
  • Comment creation endpoints

Plan retry/backoff in callers and avoid burst retries for auth flows.

API Sections