Apps and keys
Apps are the isolation boundary. Secret keys are for servers, publishable keys are for allowed browser origins.
Apps
An app is the unit of isolation in FaceCard. Users, face templates, keys and usage all belong to exactly one app. A face enrolled in one app is never matched against another app, and an API call can only see the app that owns its credential.
You create apps in the developer portal. Each app has a name and a list of allowed origins. The app is always derived from the credential on the request. If a request body contains an app_id, it is ignored.
How many apps and keys you can create depends on your plan. See Plans and limits.
Two kinds of keys
| Secret key | Publishable key | |
|---|---|---|
| Format | fc_sk_live_ + 32 characters | fc_pk_live_ + 24 characters |
| Where | Your server only | Browser code |
| Header | Authorization: Bearer fc_sk_live_xxx | X-FaceCard-Key: fc_pk_live_xxx |
| Can call | Users, token verification, usage | Only POST /v1/challenges, POST /v1/enroll, POST /v1/match |
| Origin rule | A browser Origin that is not on the allow list is rejected | The request Origin must be on the allow list |
Keys are stored as SHA-256 hashes, with a prefix and the last four characters kept for display. The full key is shown once, when you create it. If you lose it, create a new key and revoke the old one.
The Origin allow list
A publishable key is public by design: anyone can read it in your page source. What stops another site from using it is the Origin allow list. For a publishable key, the API requires the request Origin header to exactly match one of the app's allowed_origins:
- The match covers scheme, host and port.
https://app.example.comdoes not matchhttps://app.example.com:8443orhttp://app.example.com. - There are no wildcards.
- Add
http://localhost:3000(or your dev port) while you develop, and remove it before launch if you do not want it.
A request from an origin that is not listed fails with 403 origin_not_allowed.
The allow list also applies to secret keys when a browser Origin is present: a secret key used from an unlisted browser origin is rejected. Secret keys belong on servers, which send no Origin header.
Keeping keys safe
- Never put a secret key in client code, a mobile app bundle or a public repository.
- Rotate by creating a new key, deploying it, then revoking the old one in the portal.
- Rate limits are per credential: 600 requests a minute per secret key, and 30 requests a minute per IP address on the challenge, enroll and match routes. See Plans and limits.