Skip to main content
Glama
README.md
# 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

A4.4/5.0

Scored across 1 tool

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues