AI authentication logic: how agents connect and sign in

three decisions in one workflow

First, establish which connection is calling Decoy. The agent supplies its display name and client ID; those labels are self-asserted, not a verified publisher identity. A token and the effective policy determine what that connection can use.

Second, obtain the information or assertion needed by the service. A password, an emailed code and a passkey assertion have different handling requirements. Third, carry out the action the person authorized. Logging in does not by itself authorize a purchase or account deletion.

the connection sequence in Decoy

Reuse a securely stored connection when an authenticated call confirms it is valid and sufficient. For a new connection, the person first registers in the Decoy iPhone app. The HTTP pairing recipe gives the exact request bodies and verification steps.

• Build one combined request for the agreed capabilities and resources; submit it through pushed authorization (PAR).
• Start the device authorization session, share its verification link and let the person approve in Decoy. Keep the device_code private; it is not the user-facing approval code.
• Poll for the token as documented, then inspect GET /api/agent/policies. Verify the actual granted resources rather than inferring access from the token’s scope names.
• Use an authorized account and a supported credential or inbox operation. Key delivery and encrypted content must be ready before claiming a secret can be read.

follow the service’s actual sign-in method

For a password login, use the approved password. For email verification, read the approved service inbox. For a passkey, request the phone-signed assertion; its private key stays on the phone. A passwordless account needs no invented password.

In the retrieval flow, the trusted agent runtime decrypts approved vault values. Decoy cannot read those values; the agent and its provider can. Keep them out of chat, ordinary logs and memory. Email ingress has its own boundary and is described in the email guide.

recover on the existing connection

A missing capability is a reason to request the needed access on the existing connection, not to start pairing again. A denied or expired grant needs the documented recovery for that result. Inspect the response instead of guessing an endpoint or widening access.

An approved reconnect carries existing grants and creation provenance to the replacement token. A brand-new pairing does not. Revocation stops future access through the connection; it cannot erase already delivered information or end a separate website session.

what a successful result looks like

For a connect-only request, success means the connection is authenticated and its effective grant matches the approved resources. If the person asked for a task too, verify that agreed action; do not create a demo account or send test mail just to prove setup. For example, the agent creates one authorized service address, independently reads it back, then reads an actual verification email addressed to it.

Keep the technical evidence in the runtime. Tell the person what is connected, what worked and anything still incomplete in a short confirmation. A token alone is not proof that the whole workflow works.

use the documented workflow

• Connect your agent to Decoy
• Access and effective grants
• Account, email and credential recipes
• Store credentials and verify the result