PII detection and pseudonymisation API

OBVELO is a pseudonymisation gateway between your application and your model provider. It replaces every personal value with a token, forwards the request, and restores the real values in the response. Nothing from request content is stored.

Quickstart

  1. Create an account at https://app.obvelo.com — the free plan needs no card — and create a key in your panel. Getting started walks through it, with the first request.
  2. Choose how your application connects — the two ways below mask the same way. There are more: see Any system.
  3. Send requests as usual. The answer comes back with the real values in place.

SDK — your model key never reaches us

The SDK sends only the text to mask to the gateway, your own model client calls the provider directly with your own key, and the values are put back in your process. The SDKs are downloaded from Downloads — see SDKs.

python

from openai import OpenAI
from pii_gateway import PiiGateway
from pii_gateway.openai import wrap_openai

gateway = PiiGateway("https://api.obvelo.com", os.environ["OBVELO_KEY"])
client = wrap_openai(OpenAI(), gateway)

typescript

import { PiiGateway } from "@pii-gateway/sdk";
import { wrapOpenAI } from "@pii-gateway/sdk/openai";

const gateway = new PiiGateway({ baseUrl: "https://api.obvelo.com", apiKey: process.env.OBVELO_KEY });
const client = wrapOpenAI(new OpenAI(), gateway);

Proxy — change one base URL

No new library: point your provider's client at the gateway and add your OBVELO key as a header. Your provider key travels in the request to the provider and is never stored or logged.

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.obvelo.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
    default_headers={"x-obvelo-key": os.environ["OBVELO_KEY"]},
)

typescript

const client = new OpenAI({
  baseURL: "https://api.obvelo.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
  defaultHeaders: { "x-obvelo-key": process.env.OBVELO_KEY },
});

Any system, not only a chat

OBVELO does not care what kind of system sends the text — a CRM, a helpdesk, an ERP, an HR system, a document pipeline, an internal tool or an agent. It cares about one thing: where your system can be connected. Pick the row that describes it.

your system…connect it bywhat changes in it
calls OpenAI, Anthropic, Gemini or Mistral and lets you set the base URLProxyOne address and one header. No new library, streaming and tool calls included.
is your own code in TypeScript, Python or .NETSDKWrap the model client you already use. Your provider key never reaches us.
can make an HTTP request, but calls no model — an export, a ticket sync, a data warehouse loadDirect APIPOST /v1/mask with text or any JSON object; keep the map if you ever need the values back.
is an MCP client — an assistant app, an editor, an agent runtimeMCP connectorA configuration entry. The assistant gets tools that mask and restore.
is an agent whose tools reach your own systemsTool gatewayTool results come back masked; arguments are restored before they reach your system.
is a person typing into a chat siteBrowser add-onNothing on your servers.

Whatever the route, the masking is the same engine with the same rules, and the same key settings apply. Two things from your own systems make it better, and neither is stored: a dictionary of the people and companies your records hold — one SDK call turns a CSV export from any system into one — and a rule profile per key, so the support bot and the legal team each get the jurisdictions they need. Give each system its own key: the key is the unit of settings, limits and the audit journal.

Authentication

Your OBVELO key goes in x-obvelo-key. It is the only name that can never be mistaken for a provider's header, so it works on every path and with every provider SDK — including Anthropic's, which uses x-api-key for its own key. On the direct API (/v1/mask, /v1/restore, /v1/inspect) x-api-key and Authorization: Bearer are accepted as well.

x-obvelo-key: $OBVELO_KEY
Authorization: Bearer $OPENAI_API_KEY     # proxy only: the provider's key, passed through

Your provider credential — Authorization, x-api-key for Anthropic, x-goog-api-key for Gemini, api-key for Azure — passes through to the provider unchanged and is never stored or logged. We never call a model on our own contract, and the proxy adds no credential of ours. In SDK mode the provider key does not reach us at all.

A key represents a system, not a person — give each application its own key.

Endpoints

Keep the request shape you already use and change only the base URL. Streaming is supported, and every surface masks with the same engine.

providerbase URL in your clientpath
OpenAI — Chat Completionshttps://api.obvelo.com/v1/v1/chat/completions
OpenAI — Responseshttps://api.obvelo.com/v1/v1/responses
Anthropic — Messageshttps://api.obvelo.com/v1/messages
Google Geminihttps://api.obvelo.com/v1beta/models/{model}:generateContent
Mistralhttps://api.obvelo.com/mistral/v1/mistral/v1/chat/completions

Your provider credential passes through unchanged, and the provider is your own sub-processor on your own contract. Each provider runs in its own container that may reach that one provider's host and nothing else. A key with the model proxy switched off in its settings is refused on these paths with 403.

Without a model at all, call the gateway directly: POST /v1/mask returns the masked text or JSON object and the mapping, POST /v1/restore puts the values back, POST /v1/inspect reports what would be masked without masking, and POST /v1/whoami tells you what a key is allowed to do.

Proxy, per provider

The same two changes for every provider: the base URL points at the gateway and your OBVELO key rides in x-obvelo-key. Everything else — the request, streaming, tools, your provider key — stays as it was. Any other client or framework that lets you set these two things works the same way.

anthropic · python

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.obvelo.com",
    api_key=os.environ["ANTHROPIC_API_KEY"],
    default_headers={"x-obvelo-key": os.environ["OBVELO_KEY"]},
)

mistral · curl

curl https://api.obvelo.com/mistral/v1/chat/completions \
  -H "x-obvelo-key: $OBVELO_KEY" -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "mistral-small-latest", "messages": [{"role": "user", "content": "Summarise the complaint from Jan Przykladowy."}]}'

gemini · curl

curl "https://api.obvelo.com/v1beta/models/gemini-2.0-flash:generateContent" \
  -H "x-obvelo-key: $OBVELO_KEY" -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"parts": [{"text": "Summarise the complaint from Jan Przykladowy."}]}]}'

The answer comes back with the real values in place. Before anything is forwarded, the gateway looks once more for values that are unambiguous on their own; if one survived, the request is refused with 422 and nothing reaches the model. A key with the proxy switched off in its settings is refused on these paths with 403.

Direct API

Mask, send the result to any model yourself, and restore the answer. The full description is OpenAPI 3.1; it is checked against the running gateway by a test, so it describes what the gateway really answers.

curl https://api.obvelo.com/v1/mask \
  -H "x-obvelo-key: $OBVELO_KEY" -H "content-type: application/json" \
  -d '{"text": "Write to Jan Przykladowy, jan@acme.example."}'
{
  "text": "Write to [Person AG26KCY5GDJM76NS73FA6RKFNP-1], [Email AG26KCY5GDJM76NS73FA6RKFNP-2].",
  "map": {
    "[Person AG26KCY5GDJM76NS73FA6RKFNP-1]": "Jan Przykladowy",
    "[Email AG26KCY5GDJM76NS73FA6RKFNP-2]": "jan@acme.example"
  },
  "stats": { "matches": 2, "labels": ["Person", "Email"], "ms": 3.1 }
}
request fieldwhat it does
textThe text to mask. Or send object — any JSON — and every string in it is masked while ids, cursors and thread ids are left alone.
mapThe map from the previous call of the same conversation. Send it back and a person keeps the same token across turns.
dictionarypeople, organizations, custom (a value and its label) and never. Used for this request and stored nowhere.
patternsYour own formats as regular expressions, on plans with custom patterns.
optionsNarrowing for this request: countries, disabledCategories, disabledLabels, profile (extended adds cities, age and nationality), inflection with inflectionLanguage, coreference, and short neverMaskValues / alwaysMaskValues lists. Options can only narrow what the key allows; level: "disabled" is refused.

The answer carries text (or object), the map to restore with, and stats. It adds dictionary when you sent one — including whether it was cut at the limit — and attachments when the body held files.

Check safetyNet before you send the result to a model. After masking, the gateway looks once more for values that are unambiguous on their own — an email address, an IBAN, a national ID, a card number. If one is still there, the answer is still 200 but carries safetyNet with a summary and positions. The SDK wrappers refuse to call the model when it is present; if you call the model yourself, do the same.

POST /v1/restore takes map with text or object and puts the values back; it is not billed. The SDKs restore locally instead, so the map never leaves your process. POST /v1/inspect returns every detection with its position, label, rule and confidence, for previews and tuning. GET /v1/whoami returns the key's plan, quota, limits and settings, and answers even when the quota is spent.

Errors

Every refusal is JSON with error, and most carry hint — a fixed sentence saying what to do. Neither ever repeats the content of your request. The SDKs put the hint into the exception message.

statusmeaningwhat to do
400The body is not what the route takes.Fix the field error names. Retrying changes nothing.
401No key, or a key this gateway does not know.Send it as x-obvelo-key. GET /v1/whoami tells you what a key is worth.
402The plan's characters for the month are spent, or the subscription is unpaid.Change the plan or allow overage in your panel.
403This key may not do this: a feature outside the plan, the proxy switched off for the key, or a suspended account.The hint names which. Change the key's settings or the plan.
413The body is over the key's limit; or an attached file is over the per-file limit (25 MB by default, maxAttachmentBytes); or the text in the attached files is over the key's per-request limit (maxCharacters).Split it; maxKB and suggestedParts say how. Send the map with each part so tokens stay the same. A file is limited and billed by the text it holds, not by its size.
422A file your file policy refuses, or — on the proxy — data left after masking.Nothing was sent to the model. Change the file policy, or send the text without the file.
429Too many requests a minute.Wait the number of seconds in retry-after. The SDKs retry by themselves.
501This address does not serve that protocol.Use the path for your provider from the table above.
502The gateway could not reach the provider, or the provider's answer was not one it can pass on.Retry; check the provider's status page. A provider that itself answers 502 is passed on with the mark described below.
503The gateway could not confirm keys with the account service for too long.Retry later. Existing keys keep working through short outages.
413 text-too-long-for-name-modelOne text in the request is too long for the gateway's name model to read in time (above about 50,000 characters), so the request was refused before the model was asked: nothing was masked or sent on, and nothing was billed.Send it in smaller parts, or ask the account's administrator to enable splitting long texts in the panel (longTextModel). The hint names both remedies.
503 name-model-unavailableThe gateway's name model did not answer, so the request was refused: nothing was masked or sent on, and nothing was billed. It applies only where the name model is in use for the request.Send the request again in a moment. If it keeps happening, the operator checks the nameModel entry of /health.

When the provider refuses, you get the provider's refusal. On the model routes an error status from the provider is passed on as it came: its status, its own error body and the headers its client library retries by (retry-after, retry-after-ms, x-should-retry, the request id and the rate-limit headers). The provider's official library raises its usual typed error: a wrong provider key is an authentication error and is not retried, an invalid request is a bad request, a rate limit keeps its retry-after. Until 15 October 2026 every one of these arrived as a 502, which those libraries retry and report as a server error.

The answer carries x-obvelo-upstream: provider. A 401, 403, 429 or 400 without that header is the gateway's own refusal, with error and hint as above. The provider's error body is relayed as written, so a token it quotes back stays a token and is not restored. If that body is not JSON (a network error page) or is larger than 32 KiB, the status is still the provider's and the body is a fixed sentence in the provider's error shape.

How masking works

Each detected value is replaced by a token: its category, a namespace that belongs to your session, and a number. The same value keeps the same token everywhere in the request — the message, tool calls and attachments — so the model can still follow who did what.

Anna Kowalska  →  [Person AG26KCY5GDJM76NS73FA6RKFNP-1]
44051401359    →  [ID AG26KCY5GDJM76NS73FA6RKFNP-2]

A later bare surname is linked to the full name mentioned earlier (coreference) and gets the same token — on by default, because a surname that slips through is a leak; switch it off in your panel if your documents are full of surnames that are also ordinary words. Case tags for inflected languages (18 languages), which let the answer be restored in the right grammatical form, are on by default in all of them: each sentence or paragraph gets a tag only where it is clearly written in one of those languages and the analyzer is certain of the case, and a text in any other language gets none. In your panel you can untick the languages your texts are never written in, or switch case tags off.

A tag is a word the model can read, and it is written only where the engine is certain: [Person 1|dative] for the person's name in the dative, [Person 1|diminutive] for a nickname such as Kasia, [Person 1|diminutive, dative] for both, and [Person 1|dative 2] for a second, different form that reads the same. Send a token back exactly as you were given it and the original wording returns; a tag the model composes itself falls back to the person's name, and a token is never left in the text. With several languages ticked, each paragraph is read in the language it is written in, and a paragraph in any other language gets no tags — a missing tag is fine, a wrong one is not.

The namespace is what keeps two sessions from both holding a [Person 1] — the defect that puts one customer's name into another customer's letter. Detection combines 704 rules across 19 categories with a name model. Structural values — thread ids, cursors, record ids — are never masked, so agent loops keep working. This is pseudonymisation: the mapping travels with the request and stays with you.

SDKs

Three SDKs — TypeScript, Python and .NET — with streaming. They restore values in your process; masking always happens on the server, so every fix reaches every client at once. A restore bug shows a token; a mask bug would show a person.

what you needTypeScriptPython.NET
Mask and restore yourselfPiiGateway, restorePiiGateway, restorePiiGatewayClient, Restore
Wrap an OpenAI clientwrapOpenAIwrap_openai—
Wrap an Anthropic client—wrap_anthropic—
Wrap a LangChain chat modelwrapChatModel——
Route any HttpClient through the proxy——PiiProxyHandler
Restore a stream chunk by chunkStreamRestorerStreamRestorerStreamRestorer
Dictionary from a CSV exportfromCsvfrom_csvDictionaryReader.FromCsv
Third-party dependenciesnonehttpxnone

typescript · any model, your own call

import { PiiGateway, restore } from "@pii-gateway/sdk";

const gateway = new PiiGateway({ baseUrl: "https://api.obvelo.com", apiKey: process.env.OBVELO_KEY });
const masked = await gateway.mask(ticket.body);
const answer = await yourModel(masked.text);   // any provider, any library
const reply = restore(answer, masked.map);

python · anthropic

from anthropic import Anthropic
from pii_gateway import PiiGateway
from pii_gateway.anthropic import wrap_anthropic

gateway = PiiGateway("https://api.obvelo.com", os.environ["OBVELO_KEY"])
client = wrap_anthropic(Anthropic(), gateway)

c# · any model client that takes an HttpClient

var handler = new PiiProxyHandler("https://api.obvelo.com", obveloKey);
var http = new HttpClient(handler);
// hand `http` to the model client you already use

The .NET SDK targets netstandard2.0 as well as net8.0, so it loads into .NET Framework add-ins of older business systems. Every SDK puts the gateway's hint into the exception message, and the wrappers refuse to call the model when the answer carries safetyNet.

The SDKs are distributed as files, not from public package registries: download them from Downloads, check the SHA-256 printed beside each, and install from the file — npm install ./<file>.tgz, pip install ./<file>.whl, or for .NET a local folder mapped in nuget.config, as the package's README shows.

MCP connector

A small MCP server that runs on your own machine and gives any MCP client five tools: mask_pii, inspect_pii, restore_pii, reset_pii_session and check_connection. It contains no masking engine — it speaks HTTPS to the gateway and to nothing else — and it keeps the session's token map in memory only.

What it is for: masking, checking and restoring documents with an assistant's help — the assistant calls a tool, the tool masks the document, and the model works on the masked text. To keep personal data out of what a person types into an AI chat, use the browser add-on; for an application, the proxy.

Claude Desktop: download the .mcpb file for your computer from Downloads and open it. Claude Desktop shows an install window that asks for the gateway key and keeps it out of the model's sight; then ask Claude to check my OBVELO connection. The steps below are for every other MCP client, and for Claude Desktop configured by hand.

Download the program for your system from Downloads: one file, nothing else to install. Unzip it into your home folder, so the program sits at ~/obvelo-mcp/obvelo-mcp (Windows: %USERPROFILE%\obvelo-mcp\obvelo-mcp.exe). Each zip carries a guide for that system. For a gateway of your own, or to write the network permission yourself, take the source package obvelo-mcp-1.1.4-source.zip and run it with Deno 2.

1. Check the key before wiring anything in

PII_GATEWAY_URL=https://api.obvelo.com PII_GATEWAY_KEY=$OBVELO_KEY ~/obvelo-mcp/obvelo-mcp --doctor

It prints the plan, what remains of the quota and whether a name model stands behind the gateway, and ends with OK or with a FAIL line saying what to fix. It never prints the key or any content, so the output can go into a support thread. It answers even when the quota is spent.

2. Add it to your client

Claude Desktop reads claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\); Cursor reads ~/.cursor/mcp.json or .cursor/mcp.json in a project. Other MCP clients take the same entry.

json · the program

{
  "mcpServers": {
    "obvelo": {
      "command": "/Users/YOUR-NAME/obvelo-mcp/obvelo-mcp",
      "env": { "PII_GATEWAY_URL": "https://api.obvelo.com", "PII_GATEWAY_KEY": "your OBVELO key" }
    }
  }
}

The program's permissions are compiled in: the OBVELO gateway and this computer, the four settings it reads, no disk, no other process. A configuration cannot widen them. On macOS, remove the download mark once before the first start: xattr -dr com.apple.quarantine ~/obvelo-mcp.

json · the source package, with Deno

{
  "mcpServers": {
    "obvelo": {
      "command": "deno",
      "args": ["run", "--no-lock", "--node-modules-dir=none", "--allow-env",
               "--allow-net=api.obvelo.com:443", "/absolute/path/to/obvelo-mcp/src/main.ts"],
      "env": { "PII_GATEWAY_URL": "https://api.obvelo.com", "PII_GATEWAY_KEY": "your OBVELO key" }
    }
  }
}

With the source package, --allow-net names the gateway and nothing else, so the connector cannot reach a model provider or any other host — you can check that in the entry you just pasted, without reading our code. PII_MCP_ALLOW_RESTORE=0 removes restore_pii entirely; without the URL or the key the connector refuses to start rather than list tools that fail.

3. Test it in the client

do thisexpect this
Open the tool listmask_pii, inspect_pii, restore_pii, reset_pii_session, check_connection
Ask: “check my OBVELO connection”Your plan, what is left this month and whether a name model stands behind the gateway — never the key
Ask: “mask this: Jan Przykladowy, jan@acme.example”Tokens such as [Person 481207] — no name, no address. The numbers are high and random on purpose.
Mention the same person again in the same conversationThe same token as before
Restart the client, then ask to restore a token from before the restartA refusal: the token was not minted in this session. It never answers with another person's name.
Point PII_GATEWAY_URL at a wrong address and call a toolAn error the model can see — never a silent “done”

On our side the connector is measured at the protocol level — version negotiation, framing, concurrency and output discipline — and checked for leaks in every tool answer. A connector cannot force a model to call it. Where masking has to be guaranteed, use the proxy: traffic cannot go around it.

Tool gateway

For an agent whose tools reach your own systems. The tool gateway sits between the agent and your own MCP server: results from your systems come back masked — names included, found by the same name model as on /v1/mask, and refused with the same name-model-unavailable answer when that model does not reply — and tool-call arguments are restored before they reach your system — so a search for a tokenised name still finds the right record. The map travels with each call and is never kept by us. Your account's tool allowlist is applied before any call goes out, and every governed action lands in the audit journal without any content.

It needs an instance pointed at your MCP server, so it is set up with us rather than switched on in the panel — ask for it through the contact form. Agents are part of every paid plan.

Browser add-on

The add-on masks the prompt box of an AI chat in Chrome or Edge before it is sent, and restores the real values in the answer on screen. Download it from Downloads and load it with Load unpacked; see the add-on page. In its settings you enter the gateway address and a gateway key from a plan that includes the add-on; a key without it is refused with a message saying so.

Where the add-on's log is

Sign in to your account panel, stay on the Account tab and scroll to Add-on activity log (it is also linked under Gateway keys). It lists every installation that reports with one of your keys and the latest events, and it downloads as CSV or JSON. The log holds the installation ID (random, made at install, no name and no user identity), the add-on version, the time and the kind of event: a heartbeat when the browser starts and every six hours, pausing and resuming, a chat site added or removed, the type of a file sent unmasked, administrator sign-in and failed sign-in, the names of settings that changed, a dictionary loaded, and removal. It never holds content: no prompt text, no values, no file names, no dictionary entries, no setting values.

The gateway keeps the events for 30 days, separately on each of its replicas, and a restart of a replica empties its copy. The panel reads them when you open the section and keeps none, so download the CSV if you need a record. An installation that has sent no heartbeat for three days is shown as not seen: the browser was closed or the add-on was removed or switched off. A new installation appears after its first heartbeat, once the add-on has the gateway address and key set. If the section says the log is unavailable, the add-on keeps working and keeps reporting; write to support with your account number.

For administrators: the account's add-on policy

The add-on's administrator and settings live in your account, not in each browser. In the account panel, Add-on policy, you choose what every browser that uses the account's key is locked to. The add-on reads the policy from the gateway with its key, keeps a copy, asks again every five minutes, and applies it locked: a person sees Managed by your organisation and cannot change any of it, not through the options page and not by writing the browser's storage. Until you save a policy, each browser keeps its own settings, so a person who installed the add-on alone with their own key stays its administrator.

settingwhat it decides
Untick a value in a promptAllowed by default. Forbidden: every detection stays masked, and values remembered as “never mask” are masked too.
Take a mask off in the file previewAllowed by default. Forbidden: a file always goes with all its masks.
Files outside the masked typesAttached with a warning (default), or refused.
Live preview, Enter, the placeholder sentenceOn or off for every browser. Masking itself cannot be paused by a person once a policy is saved.
Extra chat sitesBare hostnames. Each browser still asks its person once for permission to run on a site; browser policy cannot grant it.
How the add-on worksInteractive (default): the first press masks and shows what was masked, the second sends. Background: one press masks and sends, and nothing is shown; what is detected is masked and a value masked by mistake goes masked. Both stop when masking fails: if the gateway does not answer or refuses, the name model is unavailable, or a file comes back not masked, nothing is sent and one short line says why. It can also be set for one browser.
Categories switched off in the add-onNone by default. A ticked category (dates, addresses, …) is sent in clear from every browser, for prompts and files alike. It applies to the add-on only; your other surfaces keep the account's masking choices.
A person may switch more categories offAllowed by default, in the add-on's options. Forbidden, or whenever unticking a value in a prompt is forbidden: the add-on's own narrowing stays locked.
Stop sending when the policy is unreachableOn: a browser that has not been able to reach the policy for 7 days stops sending until it can, instead of carrying on with its own settings. Off: it keeps the last copy it holds.

The countries and rule groups the add-on masks under are the account's own settings, Masking choices and Gateway settings, and apply to every surface; the add-on shows them read-only, and the categories switched off above narrow them for the add-on alone. Your dictionary is not part of the hosted policy: this service stores configuration, never content, so a list of names stays a file loaded into the browser (a gateway your organisation runs itself can hold one, see below). The browser's own policy (next section) still wins where both set a value, and is the only way to push the gateway address and key.

Settings for one browser. In the same section you can give a single browser settings of its own, laid over the policy: pick it from the browsers in the activity log (by the name you gave it there) or paste the installation ID the add-on shows in its options, then change only the settings that should differ. Up to 50 browsers can have their own. That browser shows Settings for this browser on its Managed by your organisation card, and still cannot change any of it. Forgetting the policy forgets these too. An installation ID is random and holds no name or content.

A browser that is not set up sends nothing. With no gateway address or key, the add-on blocks Enter, the send button, file attachments, drops and pastes on supported chat sites and says “This browser is not set up yet — contact your administrator”.

When sending is blocked, in three sentences. A browser with no gateway key is always blocked. A browser with a key but no saved policy works with the defaults, so one person can set it up alone. With Stop sending when the policy is unreachable on, a browser that has not been able to reach the policy for 7 days stops sending until it can.

Private windows. Chrome and Edge run no extension in an incognito or InPrivate window unless the person allows it, and no policy can do that for them. Close those windows with IncognitoModeAvailability = 1 (Chrome) or InPrivateModeAvailability = 1 (Edge). Firefox can allow the add-on there with "private_browsing": true in ExtensionSettings. The add-on reports whether its browser allows it in private windows, and the activity log shows a browser that does not as not protected in private windows.

Your own gateway. On a gateway your organisation runs itself, the same policy is edited at /admin/addon-policy on that gateway and stored on your own disk. Sign in with your own OpenID Connect identity provider (Entra ID, AD FS, Keycloak, any other), with a local administrator created at install, or both. Signing in at the provider does not make anyone an administrator: you name the people, by address or by group.

Your own dictionary, on your own gateway. There, and only there, the administrator can upload one organisation dictionary (a .csv, .tsv or .txt file, up to 20,000 entries) on the same page. It stays on your gateway's disk and is served to the add-ons that use that gateway; it never reaches OBVELO. Each browser downloads it when it changes and uses it together with the person's own dictionary. The change record keeps counts, never an entry.

The per-browser administrator password is being retired. This release keeps it working for existing installations and the account policy wins over it; it is removed in the next release.

For administrators: set it up through browser policy

Install the add-on on every managed browser with the ExtensionInstallForcelist policy and push its settings the same way, once. The add-on then starts configured: nobody types an address or pastes a key. A setting your policy sets wins over anything stored in that browser and over the add-on's own administrator lock; on the add-on's options page it shows Set by your organisation's policy and cannot be changed. When the browser picks up a changed policy (on its own schedule, or at once with Reload policies on chrome://policy), the add-on follows it without a restart. Leave a key out and that setting stays with the person, or with the add-on's administrator lock.

policy keytypewhat it sets
gatewayUrlstringThe gateway every prompt is masked through, for example https://api.obvelo.com.
tenantKeystringThe gateway key. Leave it out to let each person enter their own.
enabledbooleantrue keeps masking on and removes the switch that pauses it.
maskOnEnterbooleantrue makes Enter mask the prompt before it is sent, even while the live panel is open.
unmaskableFilesstringwarn attaches a file that was not masked as it is, with a warning; block refuses it.
fileUnmaskingstringallow lets a person take a mask off a value in the file preview, after a warning; forbid sends every file with all its masks.
promptUnmaskingstringallow lets a person untick a detected value in a prompt and send it as written; forbid sends every detection masked.
tokenInstructionbooleantrue adds one sentence to a message that carries masked data, asking the model to keep the placeholders as written; false never adds it.

The browser checks each value against the add-on's schema and drops one that does not fit, such as "Block" for unmaskableFiles; chrome://policy (in Edge, edge://policy) shows what arrived. A gateway address or key the add-on cannot use stays locked and masks nothing, and the options page says why. In every example below, replace <extension ID from the Chrome Web Store> with the add-on's ID from its Chrome Web Store page. Edge uses the same ID when the add-on is installed from the Chrome Web Store.

reg · Windows, Chrome (Group Policy or a .reg file)

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\3rdparty\extensions\<extension ID from the Chrome Web Store>\policy]
"gatewayUrl"="https://api.obvelo.com"
"tenantKey"="your OBVELO key"
"enabled"=dword:00000001
"maskOnEnter"=dword:00000001
"unmaskableFiles"="block"

For Edge the values are the same under HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\3rdparty\extensions\<extension ID from the Chrome Web Store>\policy. A boolean is a REG_DWORD, 1 for true and 0 for false.

plist · macOS, a configuration profile from your device management

<!-- preference domain: com.google.Chrome.extensions.<extension ID from the Chrome Web Store>
     Edge: com.microsoft.Edge.extensions.<extension ID from the Chrome Web Store> -->
<plist version="1.0">
<dict>
  <key>gatewayUrl</key>      <string>https://api.obvelo.com</string>
  <key>tenantKey</key>       <string>your OBVELO key</string>
  <key>enabled</key>         <true/>
  <key>maskOnEnter</key>     <true/>
  <key>unmaskableFiles</key> <string>block</string>
</dict>
</plist>

json · Linux, a file such as /etc/opt/chrome/policies/managed/obvelo.json

{
  "3rdparty": {
    "extensions": {
      "<extension ID from the Chrome Web Store>": {
        "gatewayUrl": "https://api.obvelo.com",
        "tenantKey": "your OBVELO key",
        "enabled": true,
        "maskOnEnter": true,
        "unmaskableFiles": "block"
      }
    }
  }
}

Chromium reads the same file from /etc/chromium/policies/managed/, Edge from /etc/opt/edge/policies/managed/.

Access to the gateway. OBVELO's hosted gateway, https://api.obvelo.com, needs nothing more. A gateway your organisation runs itself has to be allowed once in each browser, and no browser policy can grant that: the add-on's options page and the chat page both show Allow access, and until someone allows it, nothing is masked and nothing is sent. Extra chat sites cannot be set by policy for the same reason: each one needs a permission only the person can grant, and a site without it would not be covered while your policy said it was. Add them in each browser's options instead.

The add-on's heartbeat tells your gateway whether a policy sets any of these settings in that browser, never which values; the account panel shows it in the Add-on activity log.

Attachments

By default a file inside a request is passed on and named in the answer, so a file never goes through unnoticed. Choose mask in your account panel and files are masked with the same engine and token state as the surrounding text, then rebuilt in their own format so they still open — including authors, comments, reviewer lists, slide masters, chart labels and named ranges. A PDF and a scan are the exception; see below. The format is recognised from the content, never from the file name. File masking applies to the model proxy and to the object field of /v1/mask; the text field has no way to return a file.

A PDF with a text layer cannot be edited in place, so on the object field it comes back as its masked text: media_type becomes text/plain, .txt is added to its name, and the item in the answer carries "convertedTo": "text". The model proxy forwards such a PDF as its masked text too. Under mask, the model proxy and the MCP tool gateway refuse a request that carries a file that cannot be masked (422, with a hint) instead of forwarding it.

An old binary Office file cannot be edited in place either. Conversion is part of every plan, with no add-on. On a gateway that runs the converter (LibreOffice in its own container with no network, macros never run) a .doc, .xls or .ppt comes back as a masked .docx, .xlsx or .pptx: the name and media_type change with it and the item carries "convertedTo": "docx" (or xlsx, pptx). Without the converter the file is refused with conversion-unavailable and a hint — save it as .docx, .xlsx or .pptx and send it again — and it is never passed on. An Outlook .msg comes back as a masked .eml ("convertedTo": "eml", message/rfc822), with its attachments masked by the same path. RTF, e-mail, HTML and XML keep their own format: only text is masked — never a tag, a control word or a MIME boundary. In HTML, a JSON data island (<script type="application/ld+json"> or application/json) has its string values masked and stays valid JSON; ordinary JavaScript is left as it is.

masked

docx · xlsx · pptx · csv · txt · rtf · eml · html · xml (markup kept) · msg (as eml) · doc · xls · ppt (as docx · xlsx · pptx, where the gateway runs the converter) · pdf with text (as text) · with OCR, on every paid plan: scans, photos and images (as text, ocrPages per file)

not masked — reported

scans on a plan without OCR (no-text-layer, not-a-container) · a scan OCR could not read (ocr-refused with ocrReason; quota-exhausted means the plan’s monthly OCR page cap is spent, and the item carries a hint) · password-protected pdf (encrypted) · provider file ids

The map in the answer carries the tokens minted inside the files too, so whatever the model writes about a person named only in the contract can be restored. Screenshots of every surface: file masking.

When a file cannot be masked, the response says so and why. What happens next is your account's file policy, set in the panel: flag — report it and pass it on (the default), mask what can be masked, or block — refuse any request that carries a file.

A request can also ask for a policy of its own with options.attachmentPolicy (pass, flag, mask or block, loosest to strictest). It is honoured only when it is stricter than your account's: an account on flag that asks for mask gets its file masked, while an account on mask or block keeps its policy whatever the request says. The answer's attachments.policy names the one that ran, and a file left alone because of the policy carries reason: "policy-flag" (or policy-pass, policy-block) with a hint. The browser add-on asks for mask on every file it sends. It also sends attachmentPreview: true: each masked file's item then carries preview.segments — the file's text as the returned file holds it, with every token by position, its category and the value it replaced — read out of the returned bytes, so the add-on shows the person exactly what the site will receive before the file is attached. The preview costs no extra characters. options.neverMaskValues and options.alwaysMaskValues work on files as on text, on every occurrence in the file. A request carrying an inline file may be larger than your key's body limit by that file — up to 25 MB per file by default, as GET /v1/whoami reports in limits.maxAttachmentBytes, provided the request declares its Content-Length — because a document is mostly pictures and layout: what is limited and billed is the TEXT taken out of it, at most your key's body limit in characters per request. A text file is recognised by its content as UTF-8; a file saved in another encoding, such as the Windows-1250 that Excel writes for a Polish “CSV”, comes back untouched with not-a-container — save it as “CSV UTF-8”.

Custom lists and formats

Send your own dictionary with the request: people, organisations, labelled values of your own, and words that must never be masked. Up to 20 000 entries, used for that request and stored nowhere; a longer list is cut at the limit, and the response says so. One SDK call turns a CRM or ERP export into a dictionary.

Custom formats — such as internal client codes — are available from the Starter plan.

Rule profiles

Each key carries its own profile: jurisdictions and a selection of rules. The profile belongs to the credential, not to a request header, so a caller cannot switch it — a profile a caller can name is a profile any caller can claim.

In the account panel these profiles are usage groups (Keys → Usage groups): create a group for each way your keys are used — the browser add-on, agents and MCP, chat apps through the proxy, a back-end service — assign each key to one, and set per group the masking profile, the name model mode, the model proxy, which masked values may be restored, the masking lock, the countries, the tools allowed through the MCP tool gateway and what happens to a model request that declares a tool outside that list, and the group’s own rule choices — switched-off categories and labels and the opt-in groups — which replace the account’s for that group’s keys. A key in no group uses the account settings.

Limits

Plans are billed by characters. The hard cap is on by default — traffic stops rather than producing an unexpected invoice. Detection quality is identical on every plan, and so are the features: from the Starter plan every one is on, and plans differ in volume. No plan limits the number of people on an account.

A file is billed once, by the text it holds. Each masked file in an answer carries a receipt; send it back in fileReceipts with the next reading of the same file — the browser add-on does this while a person edits the file’s masks — and for ten minutes those readings are not billed again. Text sent beside the file is billed as usual. Nothing is stored: the receipt is signed by the gateway over your account, the file and the expiry.

OCR is billed like any other text: the characters it reads count towards the plan and, above it, towards the plan’s own overage. The OCR column is a monthly page cap that protects the reading service — not a price. A file past the cap comes back untouched, named, with a reason and a hint.

plancharacters / moreq / minkeysOCR pages / mo
free1 M601—
starter10 M300unlimited1 000
standard50 M600unlimited3 000
pro200 M3 000unlimited10 000
enterprise1 B12 000unlimited50 000

Data handling

The data plane stores nothing from request content; the control plane stores the account, the plan and usage in numbers, and never sees content. Hosting and every sub-processor are in the EU or EEA. In a deployment in your own infrastructure, the gateway also keeps a content log for up to 30 days on your servers, encrypted with your key and readable only by your administrators; we never see it.

If the control plane is unavailable, the gateway keeps serving existing customers from its last snapshot; only new registrations wait.

Ready to try it?