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…"
}
link_urlis the one to use: a Universal Link. Show it as a QR code (the iPhone camera opens Trowyn) or send it to the user. Without the app it shows a page with the QR and the code.qr_payloadis the oldertrowyn://form, for QR codes scanned inside Trowyn. Still supported.codecan be typed into Trowyn (Menu → Push approvals → Link a company).client_tokenlets a browser read this code's status with client-status.- A user can link several iPhones; each one gets the requests.
- Optional: add your TOTP enrollment as a backup code by appending
&t=<encoded otpauth URI>tolink_url/qr_payloadon your side. It's never sent to Trowyn. See Backup codes.
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": [] }
}
- Show
match_numberon your sign-in page ("Tap 37 in Trowyn"). The phone offers three numbers; choosing the wrong one denies the request (deny_reason: "number_mismatch"). If your policy turns number matching off,match_numberisnulland the phone shows Approve / Deny. push.sent: 0doesn't mean failure: the request still appears when the user opens Trowyn.404 no_linked_device: the user has no phone linked in this environment.- Limits: 5 requests per user per minute (stops push-bombing) and 120 per organization per minute.
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.