Ask a question on your paired phone and wait for an answer
Sends a question — with 2–4 answer choices (default ["Approve","Deny"]) — to the phone paired with the user behind the bearer token. The phone shows it as a high-priority notification; the first tap wins.
Idempotent duplicates. Re-sending the same idempotency_key (or, when it’s omitted, the same question + choices from the same token) while a matching interaction is within its idempotency window (until its expires_at) returns the existing interaction with 200 instead of creating a new one — no second prompt reaches the phone. This holds even after the phone has already answered: the idempotency key outlives the answer, so a duplicate create after an answer still returns the same (now-answered) interaction’s id, not a fresh one. A genuinely new request returns 201.
Poll the result with GET /v1/interactions/{id}. Each owner may have at most 10 pending interactions at once (429 too_many_pending); the owning account must have a paired phone device (409 no_phone_device).
Phone-capability gate. If the paired phone’s reported app build is too old to show the prompt, the request is refused outright (426 phone_app_outdated) rather than accepted and silently dropped on arrival. A phone that has never reported its version is allowed through anyway (unknown builds fail open), but this is not yet surfaced back to the caller for this endpoint.
Authorizations
Opaque bearer token created on your paired Android phone. The format is rfk_live_ followed by 32 URL-safe alphanumeric characters (≥160 bits of entropy). Test tokens use the rfk_test_ prefix.
Body
The question shown on the phone. 1–1000 characters.
"Deploy to production?"
Answer labels rendered as buttons. 2–4 entries. Default ["Approve","Deny"].
2 - 4 elementsSeconds until the ask expires. 60–86400, default 600.
60 <= x <= 86400600
Client-supplied dedup key; server derives one from content hashes when absent.
1 - 128Response
Idempotent duplicate — an existing interaction with the same idempotency key, still within its idempotency window (until its expires_at), was returned instead of creating a new one. No new prompt was sent to the phone. Can surface an already-answered interaction's id if the duplicate arrives after the phone answered but before expiry.