Gate API
Put the gate in front of your own software.
Two calls. POST /api/v1/protect swaps client data for placeholders before text goes to an AI, a vendor or a log. POST /api/v1/restore puts the real values back into whatever comes back. The firm's industry template, names settings, topics and client list all apply, exactly as in the extension. The developer reference has a full JavaScript round trip; this page adds what an IT reviewer needs.
Keys
- The owner or an IT admin creates keys in Your firm, Account, Advanced, Gate API keys (IT admins reach it from People, Advanced). SOPHIA XT support acting for the firm can't. If an IT admin is removed, the keys they made are revoked. A key starts with
sdk_, is shown once, and only its hash is kept. - Send it on every request as
Authorization: Bearer sdk_..., withContent-Type: application/json. - Revoking a key on the Gate API keys page stops it at once. A password change does not revoke keys, so an integration keeps working; if you think someone else used the owner's account, revoke the keys and make new ones. Every create and revoke is recorded under Your firm, Account, Advanced, Activity log, Activity, which the owner reads.
- Keep keys on a server. Never put one in a web page, a mobile app or a shared spreadsheet.
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."}'
{
"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...."
}
| Field | Meaning |
|---|---|
outcome | clean, redacted, alerted (the owner was notified) or blocked. |
protected_text | What to send onward; null when blocked. Passwords, keys and privileged material are always blocked. In strict mode the identifiers the template marks Stop are blocked, and everything else caught is removed rather than swapped. Names, addresses and dates the firm sets to Flag are left as written and reported to the owner. |
findings | What was caught, by rule, never the value. kept is true for items the firm set to Flag: reported to the owner, left in the text as written. |
vault | The swap table, sealed with AES-256-GCM and bound to the account that owns the key. Nobody holding it can read or change it. Send it back with the next protect in the same conversation, so the same value keeps the same placeholder, and with restore. |
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.
Errors
Every error has the shape {"error": {"code": "...", "message": "..."}}.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | A required field is missing, or the body isn't valid JSON. |
| 400 | bad_vault | 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 | restore while the firm uses strict mode. Nothing is filled back in, whatever vault was kept from before the switch. |
| 413 | too_large | Text over 100,000 characters. 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 a limit below. Wait the number of seconds in Retry-After. |
Limits
| Limit | Value |
|---|---|
| Requests per key | 600 a minute |
| Requests per network address, any key | 1,200 a minute |
| Text through the gate for the whole firm | 4,000,000 characters a minute, shared with the extension and the desk |
| Text per call | 100,000 characters |
| Different client values per vault | 500 |
Metering
The Gate API is included in the seat. protect and restore are not billed by use. The characters passing through are counted, at about four characters a token, for the admin panel only. The only thing billed by use in Safe-Desk is AI inside Safe-Desk's own chat, 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 the database or the logs. The owner's log records that a call was made through the API, which account's key made it, the outcome and which rules fired. Alerts reach the owner the same way as from the extension. All traffic is HTTPS.