Gate API
Put the gate in front of anything you send out.
Two calls. protect swaps client data for placeholders before your text goes to an AI, a vendor or a log. restore puts the real values back into whatever comes back. The same industry rules, names settings and client list as your firm's desk apply.
Keys
The owner or an IT admin creates keys in Owner view, API tab (Setup, API for an IT admin). A key is shown once; we keep only a hash of it. Send it on every request:
Authorization: Bearer sdk_…
A key acts for the person who made it: a vault from one person's key can only be restored with a key made by the same person. If an IT admin is removed, their keys stop working. Revoke a key and it stops working immediately. Changing or resetting a password does not revoke keys, so a password change never breaks your integration; if you think someone else used the owner's account, revoke the keys on the API tab and make new ones. Keep keys on your server; never put one in a web page or a mobile app.
POST /api/v1/protect
curl https://desk.sophiaxt.com/api/v1/protect \
-H "Authorization: Bearer $SAFE_DESK_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Client Dana Reyes, SSN 123-45-6789, needs a letter."}'
Response:
{
"outcome": "alerted",
"protected_text": "Client [NAME_1], SSN [SSN_1], needs a letter.",
"findings": [
{ "rule": "ssn", "label": "Social Security number", "action": "alert", "kept": false },
{ "rule": "name", "label": "Person's name (detected)", "action": "redact", "kept": false }
],
"vault": "v1.…"
}
This example is for protect-and-restore mode, the default. The owner chooses the mode on the Template tab.
| Field | Meaning |
|---|---|
outcome | clean, redacted, alerted (the owner was notified) or blocked. |
protected_text | The text to send onward. null when blocked. Passwords, keys and privileged material are always blocked. If your firm uses strict mode, SSNs, card and account numbers and the other identifiers your template marks Stop are blocked. Everything else the rules catch is removed rather than swapped, so there is nothing to restore. Names, addresses and dates your firm sets to Flag are left as written and reported to the owner. |
findings | What was caught, by rule. Never the values. kept is true for items your firm set to Flag: they are reported to the owner but left in protected_text as written. |
vault | The swap table, sealed with AES-256-GCM and bound to the account that owns the key. You can't read it and neither can anyone you pass it to. Send it back with the next protect call in the same conversation so the same value keeps the same placeholder, and with restore. |
POST /api/v1/restore
curl https://desk.sophiaxt.com/api/v1/restore \
-H "Authorization: Bearer $SAFE_DESK_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Letter for [NAME_1] ([SSN_1]).", "vault": "v1.…"}'
{ "text": "Letter for Dana Reyes (123-45-6789)." }
A placeholder inside a link or a bare web address stays a placeholder, for example https://example.com/?q=[SSN_1]: pasted into mail or a document, the address becomes a live link that would carry the real value to that site. If your integration needs every placeholder filled, send "restore_links": true.
A full round trip in JavaScript
const gate = (path, body) => fetch(`https://desk.sophiaxt.com/api/v1/${path}`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SAFE_DESK_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
}).then((r) => r.json());
const p = await gate("protect", { text: userText });
if (p.outcome === "blocked") throw new Error("Stopped by Safe-Desk: " + p.findings.map((f) => f.label).join(", "));
const answer = await yourModel(p.protected_text); // your AI never sees the values
const { text } = await gate("restore", { text: answer, vault: p.vault });
Errors and limits
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request, bad_vault | Missing fields, or a vault this key's account didn't issue, or one that was altered. |
| 401 | unauthorized | Missing, wrong or revoked key. |
| 402 | inactive | The firm's subscription isn't active. |
| 409 | strict_mode | Your firm uses strict mode, so removed details are not filled back in. Show the answer as it is, with its placeholders. |
| 413 | too_large | Text over 100,000 characters, on protect or restore. It is refused, never cut short. |
| 413 | too_many_values | More than 500 different client values in one vault. Start a new conversation without the old vault. |
| 415 | unsupported_media_type | The body wasn't sent as Content-Type: application/json. |
| 429 | rate_limited | Over 600 requests a minute for one key, or more than 4,000,000 characters a minute through the gate for your whole firm. Retry after the Retry-After seconds. |
Metering
The Gate API is included in the seat: protect and restore are not metered or billed by use. Only AI inside Safe-Desk is billed by use, and only beyond the $5 of AI per person included each month.
What the API stores
Nothing you send. The text, the protected text and the values are never written to our database or logs. Your owner's log records that a call was made, by which key's account, and which rules fired. All traffic is HTTPS.