argus-face
# argus-face
Face Terminal is an HTTP API that checks a selfie shows the same person as an ID document or photo, and that the selfie is a genuine capture, not a printout, screen, mask or synthetic face. When the reference is a passport, ID card, residence permit or driving licence, the document is checked too.
This repo holds the API spec, short client examples and a small MCP server. The face, spoof and document models are not in this repo.
- API docs: https://face.unbackoffice.com/docs
- Plain-text guide for agents: https://face.unbackoffice.com/llms.txt
- Tiers: https://face.unbackoffice.com/tiers
- Free key: https://face.unbackoffice.com/key (sign in with a work Google account)
## Try it
```sh
export FACE_API_KEY=... # your key
curl -s https://face.unbackoffice.com/v1/face/verify \
-H "X-API-Key: $FACE_API_KEY" \
-F reference=@id-photo.jpg \
-F selfie=@selfie.jpg
```
## Endpoints
Base URL `https://face.unbackoffice.com`. Send the key in the `X-API-Key` header.
| Method | Path | Body (`multipart/form-data`) |
|---|---|---|
| POST | `/v1/face/verify` | `reference` (required: ID document page or clear face photo), `selfie` (required: taken now), `back` (back of an ID card or licence). JPEG, PNG or WebP, up to 12 MB each |
| POST | `/v1/face/flash` | Free, single-use flash challenge for a live capture clip recorded with `liveness.js` in your own page. See the docs |
The full spec is in [`openapi.json`](openapi.json).
## Response
Trimmed. Real responses carry more detail per check.
```json
{
"result": {
"status": "verified",
"verified": true,
"reasons": [],
"match": {"assessment": "match", "similarity": 0.86, "confidence": 0.8, "discrepancies": []},
"integrity": {"verdict": "authentic", "confidence": 0.8, "attack_signals": []},
"liveness": null,
"document": {"decision": "genuine", "document_type": "passport", "issuing_country": "CAN", "issues": []},
"checked_at": "2026-10-11T09:30:00Z"
}
}
```
- `status`: `verified` (the faces match and the selfie looks genuine on every check that ran), `review` (something was inconclusive, `reasons` says what) or `failed`.
- `match.assessment`: `match`, `likely_match`, `inconclusive`, `likely_mismatch` or `mismatch`.
- `integrity.verdict`: `authentic`, `review` or `suspect`.
- `document.decision`: `genuine`, `review`, `suspect` or `none` (the photo is not a document; a plain face photo is fine).
A result supports a human decision. It is not a certified biometric or liveness system. Review every `review` and `failed` result before you act on it.
## Your data
Images are deleted within 24 hours of the check. The outcome (no images) is kept for 12 months. You need a lawful basis, usually the person's explicit consent, to send their face. See https://face.unbackoffice.com/terms and https://face.unbackoffice.com/privacy.
## Limits
- Your first key comes with free checks (the number is on https://face.unbackoffice.com/docs). One check is one call to `/v1/face/verify`. Flash challenges are free.
- Invalid requests are not charged. A check that could not run (`502`/`503`) is given back.
- Too many requests per minute for a key or an IP gets `429`.
- More checks: https://face.unbackoffice.com/tiers
| Status | Meaning |
|---|---|
| 400 | A file is empty, or a clip was sent without consent |
| 401 | Missing, invalid or revoked key |
| 402 | No checks left on the key |
| 403 | The key can't call that endpoint |
| 413 | A file is too large |
| 422 | A required field is missing, e.g. no `selfie` |
| 429 | Too many requests. Wait and retry |
| 502 / 503 | The check could not run and was given back. Retry shortly |
## Examples
Both read `FACE_API_KEY`, send two images and print the outcome.
```sh
# Python 3.9+, needs requests
pip install requests
python examples/python/verify.py id-photo.jpg selfie.jpg
# TypeScript, Node 18+, no dependencies
npx tsx examples/typescript/verify.ts id-photo.jpg selfie.jpg
```
## MCP server
A stdio MCP server that wraps the API, so an MCP client can run face checks. It runs straight from GitHub with `npx`, pinned to a release tag.
Each call uses one check from your key.
Tool:
- `face_verify`: `reference` and `selfie` (paths to image files on the machine the server runs on), optional `back` and `full`. Returns the status, reasons and the match, spoof and document checks, or the whole response with `full: true`.
Which files it reads:
- `face_verify` uploads the files you name to Face Terminal. It reads a path only when it is a regular file that ends in `.jpg`, `.jpeg`, `.png` or `.webp`, holds JPEG, PNG or WebP content and is 12 MB or smaller. Links are resolved first and the file they point to must pass the same checks.
- Set `FACE_ALLOWED_DIR` to a folder (several, separated like `PATH`) and nothing outside it is read. Add it to the `env` block below, for example `"FACE_ALLOWED_DIR": "/Users/you/face-checks"`.
- A path should come from you, not from a web page or a document your agent has read. A refused path gets one general message; the exact reason is in the server's log (stderr).
- Text in a result is derived from the images. Treat it as data, not as instructions to your agent.
**Claude Code**
```sh
claude mcp add argus-face -e FACE_API_KEY=your-key -- npx -y "github:sect0rial/argus-face#v0.1.1"
```
**Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project) take the same block:
```json
{
"mcpServers": {
"argus-face": {
"command": "npx",
"args": ["-y", "github:sect0rial/argus-face#v0.1.1"],
"env": { "FACE_API_KEY": "your-key" }
}
}
}
```
Restart the client after editing the file.
Pin what you run. `github:sect0rial/argus-face#v0.1.1` installs that release and nothing newer. Without the `#…` part `npx` runs whatever is on the default branch at that moment, with your API key in its environment. For the strictest pin, put the release's full commit SHA after the `#` instead of the tag (the SHAs are on the [tags page](https://github.com/sect0rial/argus-face/tags)): a tag can be moved, a commit cannot. Keep the `github:sect0rial/` prefix: this repository is the only place the server is published.
`mcp/dist` is committed so `npx` needs no build step. CI rebuilds it from `mcp/src` on every push and pull request and fails if the committed files differ.
From a clone:
```sh
npm ci # installs the locked dependencies
npm run build # compiles mcp/src to mcp/dist; commit the result with the source change
npm test # checks the path and base URL guards against a local stub (no API call, no key)
npm run verify # starts the server, runs initialize and tools/list, calls face_verify once
```
`FACE_API_URL` overrides the base URL (default `https://face.unbackoffice.com`). The images and your API key are sent to that host, so an override is refused unless it is `https` (plain `http` for `localhost` only) and `FACE_ALLOW_CUSTOM_URL=1` is set too. Leave both unset unless you run your own test server, and check any MCP config you are given for them.
## openapi.json
Saved from the live service and pretty-printed:
```sh
curl -s https://face.unbackoffice.com/openapi.json | python3 -m json.tool --indent 2 --no-ensure-ascii > openapi.json
```
Fetched on 14 November 2026, then edited: form fields that an API key cannot use are left out and the endpoint notes are rewritten. Make the same edits after a new fetch. For everything else the live document is the reference if the two differ.
## What is not here
The face match, spoof and document models run on Face Terminal's servers. They are not in this repo and not under its licence.
## Licence
The code in this repo is MIT licensed. See [LICENSE](LICENSE).
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of misselection between tools. Its purpose (1:1 face/document verification with liveness and spoof detection) is stated unambiguously in the description.
The single name face_verify is snake_case and descriptive, so there is no inconsistency to speak of. It is noun-first rather than the common verb_noun convention, but with one tool no pattern is broken.
The server wraps what appears to be a single Face Terminal verification endpoint, so one tool is defensible, but the surface is thin. There are no adjacent tools such as checking API/quota status or retrieving prior verification results, which would be reasonable companion operations.
The one tool covers the full verification lifecycle in a single call: status, reasons, face match, spoof check and document check, with clear input constraints (file paths, formats, size). Minor gaps remain, such as no way to query remaining quota or fetch historical/async results.