API reference

Base URL: https://xkxmnvnxorhwlvgcihhy.supabase.co/functions/v1
Auth: Authorization: Bearer <API key> on every call. Bodies are JSON (Content-Type: application/json).

Keep the key on your server. Never put it in a browser, mobile app, or repository. The browser only ever gets the per-request client_token (see widget).

API keys

Format Environment
trw_live_<16 hex>.<secret> live
trw_test_<16 hex>.<secret> test
trw_<12 hex>.<secret> live (older keys issued before the console; still accepted)

Create and revoke keys in the console (API keys). Only a SHA-256 hash of the secret is stored; a key is shown once. Keys are per environment: a test key only sees test links and test approvals.

POST /create-link-code

Creates a single-use code that links one of your users to their iPhone.

Field Type
external_user_id string ≤ 200, required Your stable ID for the user. Approvals are addressed to it. Don't use an email if it can change.
label string ≤ 120 Shown on the phone with your name, e.g. the user's email
ttl_seconds integer 60–900 Default 600
{
  "id": "eaaa19ca-…", "code": "K7Q2P-9XFD3", "expires_at": "2026-11-17T21:42:26.258Z", "environment": "test",
  "link_url": "https://trowyn.com/link#c=K7Q2P-9XFD3&n=Acme",
  "qr_payload": "trowyn://link?v=1&h=…&c=K7Q2P-9XFD3&n=Acme",
  "client_token": "…43 characters…"
}

POST /create-approval

Sends a sign-in request to every phone linked to the user in this key's environment.

Field Type
external_user_id string ≤ 200, required
app_name string ≤ 80, required Title on the phone, e.g. "Acme Portal"
location string ≤ 120 Free text, e.g. "Austin, TX (approx.)". Shown if your policy allows
ip_address string ≤ 64 The sign-in's IP. Shown if your policy allows
ttl_seconds integer 30–300 Default: your policy (120 unless changed)
context object, < 2 KB Stored with the request for your records. Never shown on the phone
{
  "id": "6b899e9b-…", "status": "pending", "environment": "live",
  "number_matching": true, "match_number": 37,
  "created_at": "…", "expires_at": "…", "client_token": "…",
  "push": { "configured": true, "sent": 1, "failed": [] }
}

GET /approval-status?id=…

{
  "id": "6b899e9b-…", "status": "approved", "deny_reason": null,
  "external_user_id": "user-42", "app_name": "Acme Portal", "environment": "live", "number_matching": true,
  "created_at": "…", "expires_at": "…", "decided_at": "…",
  "push": { "configured": true, "sent": 1, "failed": [] },
  "response": {
    "device_id": "…", "device_public_key": "<base64 65-byte P-256 point>",
    "signed_payload": "TROWYN-SIG-V1\nPOST\nrespond-approval\n<ms>\n<nonce>\n<sha256 hex>\n{\"approval_id\":…,\"decision\":\"approve\",…}",
    "signature": "<base64 DER>", "algorithm": "ECDSA P-256 / SHA-256 …"
  }
}
status Meaning Do
pending Waiting for the user Keep polling every 1–2 s until expires_at, or wait for a webhook
approved Right number + Face ID on a linked phone Sign the user in
denied deny_reason user (tapped Deny) or number_mismatch Refuse. Consider warning the user
expired No answer in time Refuse. They can try again

Only approved lets someone in. Treat everything else, including errors and timeouts, as a refusal. Check that external_user_id is the user who is signing in. Verifying response.signature yourself is optional: see security model.

POST /client-status

Public, CORS *, for the widget. Body {"approval_id": "…", "client_token": "…"} or {"link_code_id": "…", "client_token": "…"} (any content type). Returns only {type, id, status, expires_at, decided_at|linked_at, reason}: never the user, the number, or the device. Link status is pending, linked or expired. Wrong token or id: 404 not_found. It's for display; your server decides.

Errors

JSON {"error": "<code>", "message": "…"}.

HTTP error
400 invalid_json, missing_field, invalid_field message says which field
401 unauthorized Missing, malformed, revoked or wrong-environment key, or a live key on an org that isn't approved
404 not_found, no_linked_device
413 body_too_large
429 rate_limited Honour Retry-After
500 internal_error Safe to retry approval-status; for create-approval, retry once

Limits and retention

Per organization: 60 link codes and 120 approvals per minute; 5 approvals per user per minute; 300 API calls per IP per minute. Approval requests are kept 90 days, audit logs 180 days, link codes 1 day after expiry, unlinked links 30 days, webhook deliveries 30 days.