---
name: meeeetup-faceid
description: Use when integrating Meeeetup Face ID (api.meeeetup.com) — face check-in and identity for events, hotels and offices. Covers project API keys and scopes, the person/profile/scope data model, browser and React Native capture via @meeeetup/camera-web and @meeeetup/camera-react-native, capture sessions and their short-lived tokens, device ingest with capture keys, the detection journal, and webhook or inline capture results. Also use when reading or writing code that posts face images to a Meeeetup capture endpoint or stores a Meeeetup personId.
---

# Meeeetup Face ID

Face check-in platform: a camera captures faces, the backend resolves them to a
stable identity, and your app reads who was seen where. Identity resolution is
server-side — **your code never compares faces**.

- REST API: `https://api.meeeetup.com/v1` — schemas at
  `/v1/openapi.json`, human docs at
  <https://id.meeeetup.com/docs/api/>, agent guide at
  `/v1/llms.txt`.
- Capture SDKs (public on npm, no token): `@meeeetup/camera-web`,
  `@meeeetup/camera-react-native`.
- Console (keys, scopes, people): <https://console.meeeetup.com>.

## Read this first — the eight things that break integrations

1. **Two different credentials, and mixing them up is the most common bug.** A
   project **API key** (`sk_live_…`) is long-lived, secret and server-side
   only. A **capture-session token** is a short-lived JWT you mint per browser
   session and may safely ship to the client. Never put the API key in a
   browser, a mobile bundle, or a frontend env var.
2. **Scopes are enforced per key and fail closed with 403.** The error names the
   missing scope: `{"code":"FORBIDDEN","error":"API key missing required scope:
   scope:create"}`. Grant scopes when you mint the key in the console; a key
   cannot grant itself more later.
3. **`personId` is the identity. A record's `id` is not.** `personId` is
   stable across every scope and project in the organization — that is what you
   store and join on. It is `null` until a face links the record, so handle the
   unlinked case.
4. **The SDK never uploads.** It hands you images through a callback and makes no
   network call. Posting them is your code — that is deliberate, so the
   credential and the retry policy stay yours.
   The two upload surfaces do not even share a body shape: a capture session
   takes `{ captures: [...] }`, device ingest takes `{ images: [...] }`.
5. **A capture-session upload accepts at most 12 images per request**, while a
   passive SDK batch can hand you up to 50 faces. Chunk your posts by 12 or you
   will get a validation error under load — exactly when it matters.
6. **Browsers need HTTPS.** `getUserMedia` is a secure-context API. `http://`
   on anything but `localhost` fails with no camera and, depending on the
   browser, no error you would notice.
7. **The detector fetches WASM and a model at runtime** from
   `cdn.jsdelivr.net` and `storage.googleapis.com`. A strict CSP needs both in
   `connect-src` plus `script-src 'wasm-unsafe-eval'`. The WASM directory is
   overridable with `mediapipeWasmUrl`; **the model URL currently is not**, so a
   fully air-gapped deployment does not work yet.
8. **Throwing from your upload callback is the retry signal.** Attach a numeric
   `status`. Missing status, <400, or >=500 → the batch is requeued. A 4xx →
   that batch is dropped, because resending an unchanged rejected payload
   livelocks.

## Pick your integration shape

| You have | Use | Credential |
|---|---|---|
| A web app you control | `@meeeetup/camera-web` + capture sessions | capture-session token in the browser, API key on your server |
| A React Native app | `@meeeetup/camera-react-native` | as above |
| A fixed device / kiosk you install | `POST /capture` directly | capture key (static bearer, device-scoped) |
| A Flutter app | `@meeeetup/camera-web` inside a WebView | as web; see [Flutter](#flutter) |
| Server-side enrolment from photos you already hold | `POST /v1/persons` + `POST /v1/scopes/{scopeId}/profiles` | API key with `person:create` |
| Server-side 1:N identification against existing identities | `POST /v1/persons/search` | API key with `person:read` |
| Erase a face identity (GDPR / APPI data-subject request) | `DELETE /v1/persons/{personId}` | API key with `person:delete` |

## Data model

```
organization            ← the tenant; face identity is unique per organization
└── project             ← your API key is bound to exactly one
    ├── scope           ← a grouping: venue, event, gate, campaign
    │   └── profile     ← one person's details inside that scope
    └── journal entry   ← a detection event, references personId
```

- **scope** is a domain grouping, *not* a permission scope. The word is
  overloaded; the API uses it for both and they are unrelated.
- One profile per person per scope, so the same human can be registered at two
  venues with different details, sharing one `personId`.
- `GET /v1/scopes/{scopeId}/profiles` lists profiles for a
  scope. Each profile carries its own `id` (`profileId`) and the
  `personId` it belongs to.
- A hosted **magic link** (`account.meeeetup.com/magic/{token}`) is the
  one-at-a-time registration surface: the partner server mints it with
  `POST /v1/magic-links`, emails the URL to the user, and the
  user completes face capture + the scope's form on MeeeetUp's hosted page —
  no MeeeetUp account on the user side.

## Permission scopes

| Scope | Grants |
|---|---|
| `person:read` | list scope profiles, read a single profile, 1:N identify a face via `POST /v1/persons/search` |
| `person:create` | index a face server-side with `POST /v1/persons` and attach the resulting `personId` to a scope with `POST /v1/scopes/{scopeId}/profiles` |
| `person:unregister` | soft-delete (unregister) a scope profile |
| `person:delete` | erase a face identity organisation-wide via `DELETE /v1/persons/{personId}` (GDPR / APPI deletion requests) |
| `journal:read` | read the detection journal |
| `captureSession:create` | mint browser capture-session tokens |
| `magicLink:create` | mint hosted-registration magic links |
| `scope:create` | provision a scope |
| `scope:update` | rename a scope or replace its form |

Verify what a key actually holds before debugging anything else:

```bash
curl -H "Authorization: Bearer $KEY" https://api.meeeetup.com/v1/debug
```

No scope is required for that call, and it returns the key's granted scopes.

## Recipe: browser capture (the common case)

**Server** — mint a session per visitor. Requires `captureSession:create`.

```ts
const res = await fetch("https://api.meeeetup.com/v1/capture-sessions", {
  method: "POST",
  headers: { Authorization: \`Bearer \${process.env.MEEEETUP_API_KEY}\`, "Content-Type": "application/json" },
  body: JSON.stringify({
    scopeId,
    allowedOrigin: "https://your-app.example",  // required, and enforced
    mode: "passive",                            // "single" (default) or "passive"
    // expiresInSeconds: 300,                   // optional, 300 is the maximum
    // webhookUrl: "https://your-api/hooks/meeeetup",  // optional; omit for inline-only
  }),
});
const { sessionId, captureSessionToken, expiresAt, maxCaptures, webhookSecret } = await res.json();
```

`captureSessionToken` is the value you hand to the browser — not `token`. It
is bound to one session, one scope, one origin, `maxCaptures` and `expiresAt`,
and is accepted only by
`POST /v1/capture-sessions/{sessionId}/captures`. Revoking the
API key closes every session it minted, immediately. `webhookSecret` is
returned only when you supplied `webhookUrl`.

**Browser** — capture with the SDK, upload with your own code.

```bash
npm i @meeeetup/camera-web react react-dom
```

```tsx
import "@meeeetup/camera-web/styles.css";
import { MeeeetUpCamProvider, CameraViewport, FaceCounter, FaceGrid } from "@meeeetup/camera-web";

<MeeeetUpCamProvider
  mode="passive"
  onBatchCapture={async (faces) => {
    // The endpoint takes `captures`, max 12 per request — chunk the batch.
    for (let i = 0; i < faces.length; i += 12) {
      const res = await fetch(
        \`https://api.meeeetup.com/v1/capture-sessions/\${sessionId}/captures\`,
        {
          method: "POST",
          headers: { Authorization: \`Bearer \${captureSessionToken}\`, "Content-Type": "application/json" },
          body: JSON.stringify({
            captures: faces.slice(i, i + 12).map((f) => ({
              image: f.dataUrl,                                // data:image/jpeg;base64,…
              capturedAt: new Date(f.createdAt).toISOString(),  // createdAt, NOT lastSentAt
            })),
          }),
        },
      );
      if (!res.ok) throw Object.assign(new Error("send failed"), { status: res.status });
    }
  }}
>
  <CameraViewport />
  <FaceCounter />
  <FaceGrid />
</MeeeetUpCamProvider>
```

- `mode="passive"` batches continuously (every 10 s by default) and is what a
  walk-through gate wants. `mode="interactive"` captures one aligned face on
  user action, for a kiosk — supply `onCapture` instead.
- `@meeeetup/camera-core` installs as a dependency; name it explicitly only if
  you drive `FaceCaptureSession` yourself.
- Each face carries `createdAt` (when it was first tracked). `lastSentAt` is
  send bookkeeping — never use it as a capture time.
- A flush only releases faces whose track settled more than 5 s ago, so a
  still-improving face is not sent early. The same face is re-sent at most once
  per `cooldownMs` (default 10 s).
- Read live state with `useMeeeetUpCam()`; narrow on `cam.mode` first. It
  exposes `ready`, `error`, `trackedCount`, `totalCount`, `flushBatch()`
  and camera-device controls.
- Call `flushBatch()` on `pagehide`/`visibilitychange` if you care about the
  last few seconds — nothing is flushed automatically when a tab closes.

**Results** come back inline: the captures response returns one
`{ captureId, status, … }` per posted image, positionally aligned. Supply
`webhookUrl` when creating the session if you also want async delivery — it is
optional, and omitting it attempts no webhook at all.

## Recipe: React Native

```bash
npm i @meeeetup/camera-react-native
npm i react-native-vision-camera react-native-vision-camera-face-detector \
      react-native-worklets-core react-native-fs
```

You own the `<Camera>`; the hook owns the pipeline:

```tsx
const { ready, error, trackedCount, frameProcessor } = useFaceCaptureSession({
  cameraRef: camera,
  sessionType: "passive",
  windowWidth: width,      // makes detections line up with the preview
  windowHeight: height,
  cameraFacing: "front",
  onBatchCapture: async (faces) => { /* your upload */ },
});
```

- Add Vision Camera's worklets Babel plugin first, or the frame processor never
  runs: `plugins: [["react-native-worklets-core/plugin"]]`.
- Keep `photo` enabled on `<Camera>` — the hook falls back to `takePhoto()`
  where `takeSnapshot()` is unavailable.
- `react-native-fs` is mandatory. Without it the hook reports
  `"react-native-fs is required as a peer dependency"` through `error` and
  commits nothing.
- Permissions: `android.permission.CAMERA`; iOS `NSCameraUsageDescription`.
- RN uploads whole frames rather than crops — the crop is a documented no-op on
  that platform, and the backend crops server-side.

## Recipe: fixed device ingest

Installed hardware skips capture sessions entirely: `POST /capture` with a
static **capture key** (minted per device in the console).

```jsonc
{ "images": [{ "image": "data:image/jpeg;base64,…", "capturedAt": "2026-09-17T09:00:00+09:00" }],
  "channelId": "lobby-cam-1" }   // optional; omit for a single-source install
```

Both objects are strict. `capturedAt` accepts ISO-8601 with offset or epoch ms
and falls back to server-received time. There is no top-level `capturedAt`, and
the per-image field is `image`, not `jpeg`.

## Recipe: know who a face is

1. Mint a short-lived browser session with `POST
   /v1/capture-sessions` and ship the resulting
   `captureSessionToken` to the attendee's browser (never the API key).
2. The browser uploads the captured image(s) to
   `POST /v1/capture-sessions/{sessionId}/captures`. Each
   matched result returns `profileId` + `personId`.
3. Fetch `GET /v1/scopes/{scopeId}/profiles/{profileId}` for
   that attendee's details inside this scope. `GET /v1/journal`
   shows when and where they were seen; page with `before` (the `next_before`
   from the previous response) and bound with `from`/`to`.

Prefer the hosted magic link or the browser capture SDK — those paths keep the
face image on the user's own device. The server-to-server image endpoints
(`POST /v1/persons` and `POST /v1/persons/search`)
exist for bulk-enrol flows where you already hold the image yourself and the
user is not in front of a camera.

## Recipe: server-to-server bulk enrol from face images you already hold

Use this when you already hold the face image on your server — a batch of
historical ID photos, a partner CRM dump, a migration from another system —
and the end-user is not in front of a camera. Two API calls per user; both are
API-key authenticated and never run in a browser.

**1. Index the face into the organisation's recognition collection.** Requires
`person:create`. Idempotent on the face itself: a face already indexed returns
the existing `personId` with `created: false` and `200`, so retries and
duplicates are safe. A newly indexed face returns `created: true` with `201`.

```ts
const res = await fetch("https://api.meeeetup.com/v1/persons", {
  method: "POST",
  headers: {
    Authorization: \`Bearer \${process.env.MEEEETUP_API_KEY}\`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image: "data:image/jpeg;base64,…",   // or raw base64
  }),
});
const { personId, created } = await res.json();
```

**2. Attach that `personId` to the scope with the registration form data.**
Requires `person:create`. No image on this call. Idempotent on
`(scopeId, personId)`: a second call updates the same scope profile rather
than creating a duplicate.

```ts
await fetch(\`https://api.meeeetup.com/v1/scopes/\${scopeId}/profiles\`, {
  method: "POST",
  headers: {
    Authorization: \`Bearer \${process.env.MEEEETUP_API_KEY}\`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personId,
    name: "Hanako Yamada",
    email: "hanako@example.com",
    // phone, department, formData … exactly the scope's registration shape
  }),
});
```

To identify a face without creating anything, use
`POST /v1/persons/search` instead — it returns
`{ personId }` on match or `{ personId: null }` when the face is valid but
unknown. Requires `person:read` and is side-effect free.

## Recipe: register one user via a hosted magic link

Use this when a buyer, attendee or guest needs to register a face and
MeeeetUp hosts the whole registration UX (face capture + the scope's form)
instead of embedding the SDK yourself. The user needs no MeeeetUp account.

**Server** — mint the link with your API key (requires `magicLink:create`).
`externalRef` is your own identifier for the user (its user id + order id,
usually) and is **required** — it is how MeeeetUp echoes identity back to
you, so MeeeetUp does not carry the user's email itself. `expiresInSeconds`
is optional (default is the server policy); `webhookUrl` is optional.

```ts
const res = await fetch("https://api.meeeetup.com/v1/magic-links", {
  method: "POST",
  headers: { Authorization: \`Bearer \${process.env.MEEEETUP_API_KEY}\`, "Content-Type": "application/json" },
  body: JSON.stringify({
    scopeId,
    externalRef: "order_12345",
    callbackUrl: "https://your-app.example/register/complete",
    webhookUrl: "https://your-api/hooks/meeeetup",   // optional
    // expiresInSeconds: 3600,                         // optional
    // requireLiveness: true,                          // optional — runs a Face Liveness challenge on the hosted face step (#348)
  }),
});
const { magicLinkId, magicLinkUrl, token, webhookSecret, expiresAt } = await res.json();
```

Email `magicLinkUrl` to the user. It resolves to
`account.meeeetup.com/magic/{token}`; the token in the URL is itself the
auth for the three public hosted-flow routes
(`GET /v1/magic-links/{token}`,
`POST /v1/magic-links/{token}/face`,
`POST /v1/magic-links/{token}/form`) — your code never calls
those three.

**Webhooks** — if you supplied `webhookUrl`, three signed events arrive at it:

- `magic_link.opened` — fired once, the first time the user opens the hosted
  page.
- `person.registered` — fired after face capture completes. Payload carries
  the resolved `personId`.
- `profile.submitted` — fired after the form submits. Payload carries the
  `profileId` and the submitted `formData`.

Each delivery carries the capture-session signature contract:
`Meeeetup-Signature: t=<unix seconds>,v1=<hex>` where `<hex>` is
`HMAC-SHA256(webhookSecret, "<t>.<raw request body>")`. Verify over the raw
body before parsing, compare in constant time, and reject stale `t` values.

**Browser callback** — when the user finishes the form, the hosted page
redirects to your `callbackUrl` with a short-lived signed JWT (HS256, signed
with the per-link `webhookSecret`) in the query string. Verify it
server-side before trusting the identity it names:

```ts
import jwt from "jsonwebtoken";
const payload = jwt.verify(callbackToken, webhookSecret, { algorithms: ["HS256"] });
// payload: { magicLinkId, personId, profileId, externalRef, iat, exp }
```

The webhook stream and the signed callback token carry the same facts; either
is enough on its own. Prefer the webhook when you want the record to land
even if the user never comes back; prefer the callback token when you want to
finish the user's flow in the same browser session.

## Recipe: provision a scope from your own system

`POST /v1/scopes` needs `scope:create` and is **idempotent
via `externalId`**: retrying with the same `(project, externalId)` returns the
existing scope with `200` instead of creating a duplicate with `201`. Use your
own event id as `externalId` and stop tracking Meeeetup ids separately.

`PATCH /v1/scopes/{scopeId}` (`scope:update`) changes `name`,
`slug` or `formSchema`. `externalId` is immutable — a different source event
means a new scope. A colliding `slug` is `409`; a scope outside your key's
project is `404`. Pre-GA, `formSchema` is replaced wholesale, with no form
versioning.

## Flutter

There is no Dart package and one is not planned. Embed the web SDK in a WebView
(`flutter_inappwebview` is the reliable choice):

- grant camera access in `onPermissionRequest`, and set
  `allowsInlineMediaPlayback: true` with
  `mediaPlaybackRequiresUserGesture: false`
- iOS 14.3+ only — WebRTC does not exist in WKWebView below that
- `NSCameraUsageDescription` plus `android.permission.CAMERA`
- the page must be served over HTTPS, and the WebView must reach the two
  MediaPipe origins in gotcha 6

## Errors

| Status | Meaning | Do |
|---|---|---|
| `401` | missing or invalid key | check the `Authorization` header and the key prefix |
| `403` | key lacks the scope the endpoint requires | read `error` — it names the scope — and re-mint the key |
| `404` | resource outside your key's project | confirm the key belongs to the project you think |
| `409` | slug collision on scope create/update | choose another slug |
| `4xx` from your own upload sink | permanent for that batch | fix the payload; the SDK drops it |
| `5xx`/network from your sink | transient | the SDK requeues, bounded at 200 buffered faces |

## Recipe: receive an entry event when a known attendee is matched

Set a per-project **webhook URL** in the console (project settings → Entry
webhook). On every successful match in any scope of that project, MeeeetUp
POSTs a signed JSON event to the URL. Separate from the capture-session
webhook — the entry webhook is scoped to the project, so partners don't need
to subscribe per session.

- Only matched captures fire. `no_match` / `no_face` / `error` are silent.
- Payload:

```json
{
  "type": "project.entry",
  "projectId": "prj_…",
  "scopeId": "scp_…",
  "personId": "psn_…",
  "profileId": "prn_…",
  "matchedAt": "2026-10-12T09:00:00.000Z",
  "source": { "kind": "captureSession", "sessionId": "cps_…", "captureId": "cev_…" }
}
```

- Signature header is the same contract as capture-session + magic-link
  webhooks: `Meeeetup-Signature: t=<unix>,v1=<hex>`,
  `hex = HMAC-SHA256(webhookSecret, "<t>.<raw body>")`. Verify against the
  raw request body in constant time, reject stale `t`.
- Delivery is retried with exponential backoff and dead-lettered after 10
  failures. Return 2xx; any other status is counted as a failure.
- Rotate the signing secret from the console settings page. The old secret
  stops verifying immediately.
- v1 fires the entry webhook from the browser capture-session path today.
  Device-ingest (`POST /capture`) is next; the payload shape won't change.

## Checklist before shipping

- [ ] API key lives only server-side; the browser only ever sees a
      capture-session token.
- [ ] `GET /v1/debug` confirms the key's scopes match the
      endpoints you call.
- [ ] Served over HTTPS; camera permission prompt tested on a real device.
- [ ] CSP allows `cdn.jsdelivr.net` and `storage.googleapis.com`, plus
      `'wasm-unsafe-eval'`.
- [ ] Upload callback throws with a numeric `status` so retries classify.
- [ ] `capturedAt` derived from `createdAt`, not `lastSentAt`.
- [ ] `personId` stored as the identity; the unlinked `null` case handled.
- [ ] `@meeeetup/camera-web` at `>=0.4.0` — earlier versions hang under React
      StrictMode.
