The Ultimate Headless Backend.
You don't have to use our UI. Aeion OS was engineered from day one to function as a world-class, headless Backend-as-a-Service (BaaS). By leveraging our Global API Protocol, you can power your custom mobile apps, Unity games, and enterprise dashboards with an architecture featuring sub-millisecond pagination, native multi-tenant routing, and cryptographically secure Webhooks.
Built for Extreme Scale
Native Multi-Tenant Routing
Don't build custom sub-domain parsers. The Global API automatically routes requests using the `x-tenant-id` header or seamless subdomain mapping. The kernel intercepts the request and instantly scopes it to the correct tenant's data, making accidental cross-tenant data leaks impossible.
Sub-Millisecond Cursor Pagination
Traditional `offset` pagination destroys database performance on large tables. Aeion OS enforces strict cursor-based pagination on every collection by default. Sorting millions of CRM records or Spatial 3D coordinates executes in under a millisecond with zero table-scan penalties.
Filter AST Engine
Complex queries shouldn't require custom endpoints. The API supports a deep Filter AST via bracket notation (`?where[price][gt]=100`) or URL-encoded JSON. The kernel validates the query against your collection's schema and translates it directly into an optimized, injection-safe SQL query — no hand-written search endpoint required.
Cryptographic Webhooks
The BaaS protocol features an enterprise webhook registry. The engine signs every outgoing event with an HMAC-SHA256 signature (`timestamp.body`), ensuring your receiving servers can mathematically verify that the payload originated from Aeion OS and defend against replay attacks via a strict 5-minute window.
Unified Two-Step Authentication
The protocol separates System Auth from Tenant Auth. A single global login returns a stateful Refresh Token. Your app then hits `/api/auth/select-tenant` to exchange it for a highly-optimized, stateless JWT strictly scoped to that specific tenant's permissions matrix.
Strict Error Envelopes
Never write defensive parsing code again. The entire platform adheres to a single, unified error-envelope contract. Whether a GraphQL mutation fails, a Wasm physics crash occurs, or RBAC rejects a read, your SDK receives the exact same predictable `{ "errors": [ { "code": "FORBIDDEN" } ] }` shape.
Enterprise SLAs & Rate Limiting
Weighted Token Buckets
Aeion protects its infrastructure dynamically. The API rate limiter isn't just counting requests; it evaluates weight. A simple `GET` request costs 1 token, but a massive bulk `DELETE` costs 30 tokens. This guarantees that one noisy tenant cannot exhaust the CPU pool for others.
Live SLA Dashboard
Accountability is built-in. Aeion provides a native SLA dashboard (`/api/v1/baas/slo/dashboard`) that reports real-time p50, p95, and p99 latencies, ensuring we meet our sub-50ms latency commitments for Enterprise tiers.
Four Protocols, One Backend
REST (`/api/v1/*`)
Auto-generated 5-endpoint CRUD per collection (`GET /{slug}`, `GET /{slug}/:id`, `POST /{slug}`, `PATCH /{slug}/:id`, `DELETE /{slug}/:id`). Sparse fieldsets, cursor pagination, deep Filter AST via bracket notation, full Zod validation.
GraphQL
Single endpoint, schema introspected from registered collections. Aliased nested queries hydrate relationships in one round-trip. Subscriptions for real-time updates piggyback on the WebSocket layer.
MCP (Model Context Protocol)
89 AI-callable tools registered server-side. LLMs and agent frameworks (Claude, GPT, custom) call these as typed actions with the same RBAC enforcement as REST.
WebMCP (in-browser AI tools)
180+ tools registered dynamically by the admin panel on `navigator.modelContext`. Same RBAC, but executed in the user's browser session — page-aware collection access, admin navigation, bulk-edit workflows. The cleanest path for AI agents that need UI-level context.
Auto-Generated CRUD — Every Collection, Every Protocol
Define a collection's fields once, and Aeion generates the rest:
5 REST endpoints, validated end-to-end:
GET /api/v1/products # List with filters, pagination, fields, depth
GET /api/v1/products/:id # Read one with relationship hydration
POST /api/v1/products # Create, full Zod validation
PATCH /api/v1/products/:id # Update, optimistic-concurrency-safe
DELETE /api/v1/products/:id # Soft-delete by default, hard-delete with flag
Query string semantics, the same across all collections:
?fields=id,name,price Sparse fieldsets (include)
?fields=-internalNotes,-cost Sparse fieldsets (exclude)
?where[status][equals]=active Filter AST (bracket notation)
?where[price][gte]=100 30+ operators (eq/neq/gt/gte/lt/lte/in/contains/etc.)
?where[and][0][status]=active Logical operators
&where[and][1][price][gte]=100
?search=keyword Full-text search (PostgreSQL tsvector)
?cursor=eyJ... Cursor pagination (opaque, signed)
?offset=0&limit=100 Offset pagination (legacy)
?depth=2 Hydrate relationships up to N levels
?explain=true Return generated SQL + query plan (debugging)
?sort=createdAt:desc,name:asc Multi-field sort
Response envelope, always the same:
json
{
"data": [...],
"meta": {
"total": 1247,
"limit": 20,
"hasMore": true,
"cursor": "eyJ...",
"timing": { "db": 12, "rbac": 3, "hydrate": 7, "total": 22 }
}
}
Error envelope, always the same:
json
{
"errors": [
{
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {
"fields": {
"email": {
"message": "Invalid email",
"suggestion": "Use format: user@example.com"
}
}
}
}
]
}
A typed SDK can be machine-generated against the introspection endpoint — no hand-rolled client per collection.
The BaaS Module — Game-Engine-Scale Backend Capabilities
Push notifications
APNs + FCM + Huawei + Web Push + Slack/Discord/email fanout.
Player inventory
Atomic stack operations + full transaction history.
In-game inbox
Message system with attachments + read state.
GDPR erasure for game data
Right-to-erasure flow for player data, linked to Aegis.
Guilds
Creation, roles, permissions, and member management.
Battle pass
Seasonal pass with tier progression + reward distribution.
Tournaments
Bracket generation, match scheduling, and prize pools.
Matchmaking
Glicko-2 MMR rating with skill-based matchmaking.
Match lifecycle
Start/pause/abort/complete state machine for live matches.
LiveOps
A/B testing, feature flags, and time-limited events.
Remote config
Hot-swappable game config without an app update.
Anti-cheat
Server-side validation, anomaly detection, and ban escalation.
Leaderboards
Real-time rankings with cursor pagination over millions of entries.
Loot tables
Rarity-weighted loot evaluation with drop guarantees.
Competitive rating
Glicko-2 implementation (chess-grade competitive rating).
Marketplace
P2P trading with escrow + transaction logs.
In-game currency
Ledger with atomic transactions.
Edge functions
Deployed per tenant via the Function module.
Cloud function sandbox
Isolated WASM execution environment for cloud functions.
Function triggers
HTTP, cron, and event-driven function invocations.
Plus
achievements, bans, challenges, channels, chat, presence tracking, trades, alert evaluation, retention analytics, usage aggregation, and reward-failure recovery.
SDK Story — Generated, Not Hand-Written
Aeion auto-generates an OpenAPI 3.1 spec from your registered collections. The spec includes every collection's CRUD endpoints + every module's custom routes + every MCP tool, with full type info, request/response schemas, error envelopes, and authentication metadata.
From that spec you can generate native SDKs:
- TypeScript SDK — fully typed, async/await, AbortController-aware. Generated via
openapi-typescript-codegenor our published@aeion/sdknpm package. - Swift SDK — iOS native, supports
async/await, Combine, SwiftUI bindings. For native iOS apps that don't use the Mobile Builder. - Kotlin SDK — Android native, coroutines + Flow. For native Android apps.
- Flutter SDK — Dart, integrates with
riverpod/provider/bloc. For cross-platform Flutter. - Unity SDK — C# package with
UniTaskfor async + Unity-aware lifecycle management. For game studios. - Unreal SDK — C++ + Blueprint wrappers via
Aeion::FApinamespace. For AAA-style game backends. - Python SDK — typed via Pydantic. For data science + ML pipelines that need Aeion data.
- CLI —
aeioncommand-line tool covers every API surface from terminal.
All SDKs share: typed responses (envelope is the same), automatic token refresh, retry-with-backoff for transient failures, rate-limit aware (respects Retry-After), and structured error parsing (the unified error envelope makes this trivial).
Webhook Delivery — Reliable Outbound Events
HMAC-SHA256 signatures
Every webhook signed with `HMAC-SHA256(timestamp + "." + body, sharedSecret)`. Your receiver validates the signature before processing. 5-minute replay window blocks captured-payload re-submission attacks.
At-least-once delivery
Queue-backed retry with exponential backoff (1s, 5s, 25s, 125s, 625s, ... up to 24h). Parked in a dead-letter queue after final failure, with an operator alert.
Idempotency keys
Every webhook has a unique `X-Aeion-Idempotency-Key` header — your receiver dedupes by key. Aeion never sends two webhooks with the same key (even on retry).
Event filtering
Subscribe to specific event types: `record.created` for one collection, `payment.captured`, `user.login.anomaly`, etc. Or wildcard: `record.*` for all CRUD events on all collections.
Replay support
Per-tenant webhook log retains the last 90 days. Operator can re-deliver a specific event from the admin UI (e.g., to test a new endpoint without simulating real activity).
Per-endpoint health
Aeion tracks success rate + p99 latency per webhook endpoint. Endpoints with <50% success over a 1h window get auto-suspended with a notification — prevents a broken receiver from blocking the queue.
Frequently Asked Questions
Pick whichever fits your client. REST is simplest for typical web/mobile apps. GraphQL is best when you need nested relationship data in one round-trip. MCP is for AI agents — give your AI the credentials and it can read/write Aeion collections natively. All four protocols share the same RBAC + audit + rate-limiting layer.
Yes. We version the API at `/api/v1`. Breaking changes only ship behind `/api/v2` with a 12-month migration window. Field additions to existing endpoints are non-breaking by design. Deprecations are announced 90+ days in advance via the API itself (`X-Aeion-Deprecated` header on affected endpoints).
**Mobile / SPA:** OAuth 2.0 PKCE flow → access token + refresh token. The SDK handles refresh transparently. **Server-to-server:** API keys created via `/admin/auth/api-keys`. Keys are scoped (specific permission grants), rate-limited per key, IP-allowlisted optional, rotated via the auth module's rotation flow. **Personal access tokens:** for CLI / scripts → short-lived tokens issued via the user's account page.
Real-time updates flow through the Realtime module (LiveKit-backed). Subscribe to `record.created` / `record.updated` events for any collection over WebSocket. SSE supported on legacy clients. Both share the same RBAC layer as REST.
Yes — `POST /api/v1/batch` accepts an array of operations and returns an array of envelopes. Same RBAC applied per operation. Configured maximum 50 operations per batch by default (tunable per tenant). Useful for offline-sync mobile apps that need to flush pending changes.
Pass the tenant identifier as `x-tenant-id` header or subdomain (e.g., `tenant-slug.aeionos.com/api/v1/...`). The SDK lets you set this once on initialization. For multi-tenant clients (an admin tool managing multiple tenants), set per-request or use the `x-aeion-domain` header for subdomain-style routing.
Yes — 429 responses include a `Retry-After` header with the seconds until the bucket refills. SDKs respect this header and wait before retrying. The token bucket itself uses Redis with per-key TTLs; rate-limit state is consistent across multiple API instances under load balancing.
Yes. Build a custom Aeion module, register routes via `api.registerRoutes("/my-module", router)`, and they're exposed under `/api/v1/my-module/*` with full RBAC + rate-limiting + error-envelope conformance. The router uses Hono v4; familiar to anyone who's worked with Express/Fastify/etc.