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.type is webauthn.get;
  • the origin is https://kiff.dev, never inside another site’s frame (crossOrigin), and rpIdHash is the SHA-256 of kiff.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.