Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify access_key guidance; mark prod deploy completed in TODO__Agents.md

Browse Source
This commit is contained in:
Scott Idem
2026-03-31 12:57:43 -04:00
parent c53a993bab
commit aa5ba8c9c6
2 changed files with 34 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
documentation/GUIDE__AE_API_V3_for_Frontend.md
View File

@@ -44,6 +44,39 @@ When the frontend first loads and doesn't know the `account_id`, it performs a "
* Returns 200 + a list containing the `account_id` (random string ID) and `site_id` (random string ID).
* ** デザイン Choice:** If the domain is not found, it returns **200 OK with an empty list `[]`**. It is NOT a 404.
> **Access Key Support**
>
> Some client deployments restrict their domain to authenticated sessions via an access key set in the URL (e.g. `https://client.example.com/?key=abc123`).
>
> **How to pass the key:**
> Read the `key` query param from the browser URL. If present and non-empty, include it as `access_key` in the POST body:
> ```json
> {
> "and": [
> { "field": "fqdn", "op": "eq", "value": "client.example.com" },
> { "field": "access_key", "op": "eq", "value": "abc123" }
> ]
> }
> ```
> If `key` is absent, empty, or falsy — omit `access_key` from the payload entirely (do not send `"access_key": ""`).
>
> **Server behavior:**
> - `v_site_domain.site_access_key` (site-level) takes priority. If set, all domains under that site require it.
> - `v_site_domain.site_domain_access_key` (domain-level) is used only when `site_access_key` is not set.
> - A domain is **public** only when **both** key columns are NULL/empty — no `access_key` needed.
> - Falsy `access_key` values (empty string, etc.) are ignored server-side as a safety net.
> - A successful match returns `200` with the matching record. No match returns `200` with an empty list `[]`.
> - Do **not** use `access_code_kv_json` for this — that field is consumed by UI features and is unrelated to access control.
>
> **Examples:**
> | Browser URL | `access_key` in payload | Result |
> |---|---|---|
> | `https://dev-demo.oneskyit.com` | *(omit)* | ✅ Returns record (public domain) |
> | `https://client.example.com/?key=correct` | `"correct"` | ✅ Returns record |
> | `https://client.example.com/` | *(omit)* | ❌ Empty list (key required) |
> | `https://client.example.com/?key=wrong` | `"wrong"` | ❌ Empty list (wrong key) |
> | `https://client.example.com/?key=` | *(omit — strip empty)* | ❌ Empty list (key required) |
>
---
## 3. Standard CRUD Patterns