Docs Reference
Device signatures
How a phone or computer signs its answers to held calls with a key only that device can use. For developers of an app that answers held calls or issues Cards. Bind a P-256 key at sign-in, then sign each answer and grant; a stolen sign-in token then approves nothing.
The key lives in the device’s secure hardware (Secure Enclave, Android
Keystore, a Windows TPM). A device signed in without a key can read held
calls but not answer them (device_required). In the tafs app, see
Approving on your phone.
1. Binding the key at sign-in
Start the device sign-in (POST /v1/auth/device/start) with
public_key (P-256, base64 SPKI DER), device_name and platform
(ios, ipados, macos, android, windows or linux), and optionally
kind (iphone, ipad, android_phone, android_tablet or other).
Approving the sign-in in the browser binds the key to that session.
2. Signing an answer
Approve once, reject and change Card need
"signature": {"signed_at", "value"} in the body. value is a base64
DER ECDSA P-256 signature over the SHA-256 of these lines:
kiff.answer.v1
<tenant_id>
<exception_id>
<answer> approve-once, reject or change-card
<next_step> empty unless a refusal names one
<sha256 of the note> hex; empty when there is no note
<accounting_version> the hold's, from GET /v1/me/card-exceptions/{id}
<signed_at> RFC 3339, the same string as in the body
Refusals: signature_required, signature_invalid, and
signed_at_out_of_range (more than 5 minutes from KIFF’s clock). The
receipt keeps the signed text and signature, so anyone can check it.
change-card lasts when a per-action limit or resource scope was in the
way; for a reached total it adds room for this period only. A call that
hit both is held again after the first answer.
3. What a phone’s session may do
Read Cards and held calls, answer, revoke a Card, read receipts, list
agent drafts, and list or sign out devices. Anything else is refused
with phone_session_forbidden.
4. Signed requests
Creating an agent, issuing a Card, minting a key and giving extra room
need KIFF-Device-Signature: t=<signed_at>,v1=<signature> from a phone,
over the SHA-256 of:
kiff.request.v1
<tenant_id>
<METHOD>
<path and query, as sent>
<sha256 of the body> hex
<signed_at> RFC 3339, the same string as in the header
Refusals: signature_required, signed_at_out_of_range,
signature_replayed. A phone can mint only keys bound to an agent.
5. The approval key
An approval key needs Face ID or the passcode before it signs. Send it at
sign-in as approval_public_key, or register it once with
POST /v1/me/device/approval-key, signed by the device key. Once set,
approve once, change Card, issuing a Card, extra room, draft submit and
confirm, and resume count only with its signature
(approval_key_required otherwise).
6. The approval window
POST /v1/me/window, signed by the approval key, opens a window of up
to 5 minutes (capped at 15) for routine actions: a new Card, a narrower
revision, and a draft’s submit and confirm. Inside it, sign with the
device key as t=…,v2=…,w=<window id>. Widening a Card, extra room,
resume and sharing are never routine (critical_key_required).
7. Held-call alerts for a phone app
A signed POST /v1/me/alert-targets registers the app’s backend, if
KIFF lists it for phone apps, as the account’s alert target for
owner_required and hold_answered. See Webhooks.
8. Passkeys (coming next)
A computer with no secure key store of its own, such as an older Mac or
Linux, will approve with a passkey: the phone’s own passkey through a QR
code, or a USB security key. The assertion’s challenge is the action’s
digest: the base64url of the SHA-256 of the same kiff.request.v1 message
a device key signs. So a passkey approves exactly one action, as a device
signature does.
KIFF accepts an assertion only when every check below holds:
clientDataJSON.typeiswebauthn.get;- the origin is
https://kiff.dev, never inside another site’s frame (crossOrigin), andrpIdHashis the SHA-256 ofkiff.dev; - the challenge equals the action’s digest, byte for byte;
- the user was present and verified (the UP and UV flags);
- the signature verifies over
authenticatorData ‖ sha256(clientDataJSON)with the passkey’s registered P-256 key; - the sign counter never goes backwards (an authenticator that keeps no counter reports 0 every time);
- the passkey is registered to this account.
Registering a passkey will itself be an approval, signed by one of the account’s existing approval devices. A passkey synced to the computer’s own cloud account never counts as the second device that payments need.
The check is built. Registering a passkey, and sending an assertion in place of a device signature, come in the next change.
9. Pairing a computer from a phone
A computer shows its keys, a nonce and an expiry as a QR code. The phone
sends the QR’s JSON to POST /v1/me/pairings, signed by its approval key
(a window never covers it), and gets 201 {"pairing": {"id", "code",
"expires"}}. Refusals carry words for the person: invalid_pairing,
pairing_expired, pairing_used, key_registered.
The computer polls POST /v1/pair/claim with no auth, every 3 seconds or
more, with {"nonce", "pub", "proof"}: proof is its device key’s
signature over kiff.pair.claim.v1, the nonce and the SHA-256 of pub.
It answers authorization_pending, slow_down, expired_token or
invalid_proof, then, once, a session bound to the keys the phone
approved, with its device_id.
Your devices
GET /v1/me/devices lists them, each with its kind and a
display_name drawn from it in the request’s Accept-Language (name
is what the device sent; display_name is it for kind other);
DELETE /v1/me/devices/{id} removes one and ends its sign-ins.