Quickstart: Connect Your App

The Global API uses Two-Step Auth — first authenticate as a user (cross-tenant), then select a specific tenant context.

Step 1a — System-level login:

```typescript const loginRes = await fetch("https://api.aeionos.com/api/auth/login", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ email: "user@acme.com", password: "super-secret", }), });

const { data: { refreshToken }, } = await loginRes.json(); // refreshToken: stateful — usable across tenants you belong to ```

Step 1b — Tenant selection:

```typescript const tenantRes = await fetch( "https://api.aeionos.com/api/auth/select-tenant", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refreshToken, tenantId: "tenant_acme" }), }, );

const { data: { accessToken }, } = await tenantRes.json(); // accessToken: stateless JWT scoped to this tenant ```

Why two steps? A single user might belong to multiple tenants (employee at acme.com + customer at competitor.com). The refresh token authenticates them as a person; the access token authenticates them WITHIN a specific tenant. The kernel uses the access token's tenantId claim for all subsequent operations.

Token refresh: When the access token expires (~1 hour), use the refresh token to get a new one without re-authenticating.

For predictable performance at any scale, use cursor pagination instead of offset:

typescript // First page const page1 = await fetch("/api/v1/contacts?limit=50", { headers: { Authorization: Bearer ${accessToken}`, "x-tenant-id": tenantId }, }); const page1Body = await page1.json(); // page1Body.data: array of records // page1Body.meta.hasMore: boolean // page1Body.meta.cursor: string (use for next request)

// Next page using cursor if (page1Body.meta.hasMore) { const page2 = await fetch( /api/v1/contacts?limit=50&cursor=${encodeURIComponent(page1Body.meta.cursor)}, { headers: { Authorization: Bearer ${accessToken}, "x-tenant-id": tenantId, }, }, ); } ```

Why cursor vs offset?

• Cursor pagination: O(1) per page — DB jumps directly to the next page boundary
• Offset pagination: O(N) — DB scans through N rows to reach the offset (slow on deep pages)

Cursor characteristics:

• Opaque (URL-safe encoded internal state)
• Tied to your sort order (changing orderBy invalidates cursors)
• Stable — re-using a cursor returns the same next page
• Time-limited — cursors expire after 1 hour by default (configurable)

Sort + cursor:

GET /api/v1/contacts?orderBy[lastActivityAt]=desc&limit=50 GET /api/v1/contacts?orderBy[lastActivityAt]=desc&limit=50&cursor=eyJ...

For server-to-server notifications (order created, payment completed, etc.), register webhooks:

typescript // Register a webhook endpoint (admin API) await fetch("/api/admin/webhooks", { method: "POST", headers: { Authorization: Bearer ${accessToken}, "x-tenant-id": tenantId, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://your-server.com/webhooks/aeion", events: ["commerce.order.completed", "commerce.refund.processed"], secret: "your-shared-secret", // Never sent to Aeion API; stored on your end active: true, }), });

HMAC-SHA256 signature verification on your side:

```typescript import crypto from "crypto";

app.post("/webhooks/aeion", (req, res) => { const signature = req.headers["x-aeion-signature"]; const timestamp = req.headers["x-aeion-timestamp"]; const body = req.rawBody; // Get raw bytes, not parsed JSON

// Verify signature const expectedSig = crypto .createHmac("sha256", "your-shared-secret") .update(${timestamp}.${body}) .digest("hex");

if (signature !== expectedSig) { return res.status(401).send("Invalid signature"); }

// Verify timestamp (prevent replay attacks) const now = Date.now() / 1000; const requestTime = parseInt(timestamp); if (now - requestTime > 300) { // 5-minute window return res.status(401).send("Timestamp too old"); }

// Process the event const event = JSON.parse(body); // ...

res.status(200).send("OK"); }); ```

Reliability: Aeion retries failed deliveries with exponential backoff (1s, 5s, 25s, 2min, 10min, 1h, 6h, 24h). After max retries, the delivery is parked in the DLQ; you can manually replay via Admin → Webhooks → DLQ.

Per-tenant rate limits — webhooks subject to per-recipient throttling to prevent overwhelming your endpoint.

Aeion auto-generates an OpenAPI 3.1 spec from your registered collections.

Fetch the spec:

bash curl https://api.aeionos.com/api/docs/openapi.json > aeion-openapi.json

Generate native SDKs:

```bash # TypeScript npx openapi-typescript aeion-openapi.json -o aeion-types.ts

# Python openapi-generator-cli generate -i aeion-openapi.json -g python -o ./aeion-sdk-python

# Go openapi-generator-cli generate -i aeion-openapi.json -g go -o ./aeion-sdk-go

# Java openapi-generator-cli generate -i aeion-openapi.json -g java -o ./aeion-sdk-java

# Swift openapi-generator-cli generate -i aeion-openapi.json -g swift5 -o ./aeion-sdk-swift

# Rust openapi-generator-cli generate -i aeion-openapi.json -g rust -o ./aeion-sdk-rust ```

Generated SDKs include:

• Typed request/response models for every endpoint
• Built-in retry logic + exponential backoff
• Configurable auth (token in env var, secret manager, etc.)
• Error envelope handling with typed error codes
• Streaming support for large response bodies
• Webhook signature verification helpers

Stainless option (for enterprise SDKs with branding):

• Premium SDKs with hand-tuned ergonomics
• Stable interfaces guaranteed across versions
• Branded under your product name (e.g., "ACME API SDK" instead of "Aeion API SDK")
• Single-source SDKs for TS / Python / Go / Java / Kotlin / Swift / Ruby