The person API

• Yours works for you at once.An app you register works for your own account and up to 10 testers while it waits for review.
• Everyone else needs it verified.Review checks who publishes it, its domain, its name and logo, its privacy policy, that its scopes match what it does, and that every answer comes from a press by the person.
• The person sees who it is.Its name, its publisher and whether it’s verified are on the approval, with what it may do in plain words.
• You agree to the developer terms.Use what your app sees only to serve the person who signed it in: never sell it or train models on it. Read the developer terms.

1. Name it, and say how it signs in.A terminal or script signs in with a code on a computer set up with Pending You. A desktop or phone app, a website with a server, or a single-page web app signs in with PKCE and comes back to one of its redirect addresses.
2. List its redirect addresses, exactly.https on your website’s domain or one under it; http://127.0.0.1 or http://localhost on any port; or, for a desktop or phone app, its own scheme named for your domain backwards (example.acme.desk:/oauth for acme.example). No wildcards, at most 10.
3. Choose the most it may ask for.Its scopes’ ceiling: a sign-in asks for some or all of them, and the person sees each in plain words. A web or desktop app has no computer of its own, so it always holds cards:read:all.
4. Keep the secret on your server.A website’s client secret is shown once. Rotate it in Settings › Developers; the old one stops working at once.

Before review

• Prove your domain.Add a TXT record pendingyou-app-verification=<token> to it, or put that line in https://<domain>/.well-known/pendingyou-app-verification.txt, then press Check now. Settings › Developers shows your token.
• Add a privacy policy, terms and a support email.The policy says what your app keeps of people’s cards, and where. They stay as they are while we review it.
• Press Request review.We check who publishes it, its domain and redirect addresses, its name, its privacy policy, that its scopes match what it does, and that every answer comes from a press by the person. We write to its support email if something needs to change.

1. Make a key for the sign-in.A P-256 key that stays with your app (see DPoP below). Its thumbprint goes in the computer’s attestation, so the sign-in is bound to it from the start.
2. Have the computer vouch for it, and start.pendingyou machine attest signs an attestation with the computer’s own key (made by npx pendingyou init). A computer the person hasn’t set up can’t be allowed.
3. Show the code, and poll.The person allows it on their phone, on the card Pending You shows them, or at the link. Poll the token endpoint every interval seconds with a DPoP proof each time.

Example:Signing in with a code, in a whole appexamples/answer-cards/sign-in.ts

1. Make a key, a verifier and a state.A P-256 key for the sign-in (see DPoP below), a PKCE verifier, and a random state. Name the key’s thumbprint as dpop_jkt (RFC 9449 §10), so the code is bound to it too.
2. Send the person to Pending You.Use one of your app’s registered redirect addresses, exactly. A desktop app may listen on any port of its registered http://127.0.0.1 address (RFC 8252), or come back through its own scheme.
3. Exchange the code.Check the state that comes back, then exchange the code with the verifier and a DPoP proof by your key. A desktop or single-page app must prove it; Pending You asks for a nonce first.

• Every card.An app signed in this way has no computer, so it asks for cards:read and cards:read:all, and sees every card the person’s assistants ask them.
• One sign-in per copy.Signing in again with the same key replaces the sign-in; another copy of your app, with its own key, keeps its own. A website’s sign-in replaces the person’s earlier one.
• A website with a server.It exchanges its code with its client secret, and may skip DPoP: its tokens are then bearer tokens, which never leave its server.

Example:A desktop app’s sign-in through the browser, in a whole appexamples/answer-cards/sign-in.ts

• A new proof for every request.Its method and address (no query), the time, a random jti, and at /v1 the access token’s SHA-256 (ath). ES256 only.
• Nonces.Every answer carries DPoP-Nonce: put the latest in your next proof. The token endpoint requires one; /v1 asks again with use_dpop_nonce when yours is old. Make the proof again with the new one and send the request once more.

• Reads have ETags.Send the ETag back as If-None-Match and a read that hasn’t changed answers 304.
• Answers need an Idempotency-Key.A new key for each answer (every other change to a card takes one too). The same key and request within 24 hours get the first answer again, so a retry never answers twice.
• Show the version you answer.An answer names the card’s version. If the card changed meanwhile, it’s a 409 version_conflict: show it again and ask.

Example:Showing a card and answering it from the person’s key pressexamples/answer-cards/answer.ts

• Wait for the next change.wait holds the request up to 25 seconds until something changes. Keep the cursor and pass it back as after; without one, the feed starts from now.
• Read the cards again every 10 minutes.On start, and every 10 minutes, read GET /v1/cards too: a card that comes into reach makes no change of its own.

Example:Following the feed, and passing each change to your own serverexamples/change-feed/watch.ts

• Changes in behaviour are dated.Send Pending-You-Version: 2026-10-05 to pin one; every answer says which it followed. Anything that can’t be added waits for /v2.
• The OpenAPI document.OpenAPI 3.1 at /v1/openapi.json, made from the same definitions the API serves. Device sign-in and DPoP are in x-pendingyou-device and x-pendingyou-dpop.

Example:Every call Pending You for Herdr makes, as a terminal queueexamples/herdr-queue/

Example:Every example, with how to run itexamples/