SOPHIA XT

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.

FieldMeaning
outcomeclean, redacted, alerted (the owner was notified) or blocked.
protected_textThe 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.
findingsWhat 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.
vaultThe 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

StatusCodeMeaning
400bad_request, bad_vaultMissing fields, or a vault this key's account didn't issue, or one that was altered.
401unauthorizedMissing, wrong or revoked key.
402inactiveThe firm's subscription isn't active.
409strict_modeYour firm uses strict mode, so removed details are not filled back in. Show the answer as it is, with its placeholders.
413too_largeText over 100,000 characters, on protect or restore. It is refused, never cut short.
413too_many_valuesMore than 500 different client values in one vault. Start a new conversation without the old vault.
415unsupported_media_typeThe body wasn't sent as Content-Type: application/json.
429rate_limitedOver 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.