OSIT-AE-API-FastAPI/documentation/GUIDE__V3_FRONTEND_API.md

Aether API V3 Frontend Integration Guide (Svelte/TypeScript)

This guide defines the standards for interacting with the Aether API V3 CRUD and Action endpoints.

---

1. Authentication and Security (Mandatory)

V3 architecture enforces strict Multi-Tenant Isolation and Machine Authorization. Requests require two levels of validation.

A. The "Entry Ticket" (API Key)

Mandatory for all requests. identifies the application or client.

• Header: x-aether-api-key: <your_app_key>
• Status Code: 403 Forbidden if missing or invalid.

B. The "Visa" (Account Context)

Required for any non-public data (Journals, Badges, Users, etc.).

1. Standard Access: Provide the x-account-id (the random string ID).
   • Header: x-account-id: <account_id_random>
2. Administrative Bypass: For authorized scripts needing global access.
   • Header: x-no-account-id: bypass
3. Token Access: Provide a JWT in the query string.
   • Query Param: ?jwt=<token>

Caution

UNSUPPORTED HEADERS: The header x-aether-api-token is NOT recognized by the V3 API. If you send it, the backend will treat you as a guest and block access to private data.

---

2. Bootstrapping (The FQDN Handshake)

When the frontend first loads and doesn't know the account_id, it performs a "handshake" using its domain name.

Endpoint: POST /v3/crud/site_domain/search Body:

{
  "and": [
    { "field": "fqdn", "op": "eq", "value": "demo.oneskyit.com" }
  ]
}

Results:

• Returns 200 + a list containing the account_id and site_id random strings.
• ** ڈیزائن Choice:** If the domain is not found, it returns 200 OK with an empty list []. It is NOT a 404.

---

3. Standard CRUD Patterns

A. GET by ID

Used when the ID is known.

• Endpoint: GET /v3/crud/{obj_type}/{id_random}
• Security: Returns 403 if the record doesn't belong to your x-account-id.

B. POST Search

The primary way to retrieve data.

• Endpoint: POST /v3/crud/{obj_type}/search
• Security: Automatically filters results to only show records belonging to your x-account-id. If no account context is provided, it will return 0 records for private objects.

---

4. Troubleshooting 403 Forbidden

If you receive a 403 on a valid ID:

1. Verify x-aether-api-key is correct.
2. Ensure you are sending x-account-id and NOT x-aether-api-token.
3. Verify the record actually belongs to the account ID you are sending.
4. Check if the object is marked public_read: True in the registry. (Posts and Archive Content allow guest access; Journals and Badges do not).