API Reference

Aero2 exposes a REST API for OIDC operations and administration. All endpoints return JSON unless otherwise noted.

Base URL

https://{app-slug}.yourdomain.com

Each application has its own subdomain. All API requests are scoped to the application determined by the hostname. For example, requests to swift-maple.aero2.dev only see users, clients, and data belonging to that application.

Authentication

Endpoints use one of four authentication levels:

Error Format

All errors follow this structure:

{
  "error": "Human-readable error message"
}

Common HTTP status codes:

Pagination

Paginated endpoints accept page and limit query parameters and return a pagination object:

{
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "total_pages": 2
  }
}

Content Type

• Request body: application/x-www-form-urlencoded for OAuth endpoints, application/json for admin API
• Response: Always application/json

Sections

• Discovery — OpenID configuration and JWKS
• Authorization — OAuth2 authorization endpoint
• Token — Token exchange and refresh
• UserInfo — User claims endpoint
• Revocation — Token revocation
• Relying Party — External IdP login flows
• Sessions — Session management
• Users — User management
• Identity Providers — IdP configuration
• OAuth Clients — Client registration
• Roles & Permissions — RBAC management
• Audit — Audit trail
• Health — Health checks