Accepting agent sign-in

What you'll build: most likely nothing.

If your app already has a sign-in endpoint that returns an AuthenSee session to its caller, which is what your own front end calls, then agents can sign in today. This page shows you how to check in one minute, and what to add in the cases where something is genuinely missing.

Why this is easy: the hosted flow tells agents what to do. A provider does not have to document AuthenSee, publish anything agent-specific, or maintain a parallel integration.

The one-minute check

Look at whatever your front end calls to start a sign-in. If its JSON response contains flowCode or hostedUrl, you are done. Agents can use it.

// A typical response. Either field is enough:
{
  "sessionId": "...",
  "flowCode": "flow_...",                              // the ticket
  "hostedUrl": "https://auth.authensee.com/flow/flow_..." // ...also contains it
}

hostedUrl is literally {hosted origin}/flow/{flowCode}, so anything that hands out a hosted URL is already handing out a flow code.

How it works, with you doing nothing

Agent                          Your app                    AuthenSee
  |                               |                            |
  |  1. your normal sign-in call  |                            |
  |  ---------------------------> | POST /v1/sessions (sk_)    |
  |                               | ------------------------>  |
  |  <-- hostedUrl / flowCode ----|                            |
  |                               |                            |
  |  2. GET that URL as text (does NOT spend the code)          |
  |  ----------------------------------------------------->    |
  |  <-- a brief: your code is live, here is what to call --    |
  |                               |                            |
  |  3. prove control of its persona (ZK, on its side)          |
  |  ----------------------------------------------------->    |
  |  <-- authResultCode -------------------------------------- |
  |                               |                            |
  |  4. hands the code back the way you already accept it       |
  |  ---------------------------> | exchange (sk_)             |

Step 4 is the exchange you already do for humans. You get the same shape back, with personaType: "agent" and factorsVerified: ["agent_keypair"] telling you who you are talking to.

What the agent does

Purely for your understanding; none of it is your code. Agents use the public @authensee/agents package:

// First visit to your app: one flow code binds the persona AND signs in.
const { providerSubject, authResultCode } = await agentLinkAndAuthenticate({
  serverUrl, flowCode, ...agent, signer: agent.signer, prover,
});
 
// Every later login: one fresh code each time.
const next = await agentAuthenticateToProvider({
  serverUrl, flowCode: freshCode, ...agent, signer: agent.signer, prover,
});

When you do need to add something

Three cases, in order of how often they come up.

Your sign-in endpoint is not machine-callable

If it requires a browser session, a CSRF token, or a cookie an agent cannot obtain, then an agent cannot get a code from you. Expose something it can call. The shape is yours; the only requirement is that it mints a fresh code per call:

app.post('/api/agent/session', requireAgentCaller, async (req, res) => {
  const session = await authensee.createSession({
    scope: 'full',                       // needed for a first visit
    externalUserId: req.agent.accountId, // your stable id for this account
    ttl: 3600,
  });
  res.json({
    flowCode: session.flowCode,
    serverUrl: 'https://api.authensee.com', // the environment YOU are wired to
  });
});

Your sign-in guard blocks a returning agent

A common one. If your "sign in" path requires the account to be fully linked, note that an agent binds its persona directly with AuthenSee, so no result code reaches you and nothing in your database flips to linked. A returning agent then gets rejected before it can prove anything. Let a claimed account request a session; AuthenSee is the real boundary, since the session is scoped to that account's externalUserId and only the persona actually bound to it can prove against the code.

You want agents to find you without being told

Add a few lines to your own llms.txt naming the endpoint. Nice to have, not required: an agent that already holds a URL from you does not need it.

Controlling agent access

Per provider, in your dashboard, independent of the factor combination you require from humans:

• agentPolicy — allowed (the default) or blocked. A blocked provider rejects the agent scheme at the enrollment gate, the challenge bind, and verification.
• agentRateLimitPerMin — platform-enforced per-agent ceiling, default 30.

Human personas never get the agent scheme, and agents never satisfy a human factor.

What an agent identity is not, yet

There is no delegation. An AuthenSee agent identity is standalone: control of the keypair is the identity. There is no way for a human to grant an agent a narrowly scoped, revocable capability on their behalf, and no "acting as user X" claim. If your product needs a human to authorize an agent for specific actions, that authorization is yours to model and enforce; AuthenSee tells you which persona proved control of which key, and that is all.

Human-delegated, revocable agent identities are on the roadmap.

Next

• Agent manual — the machine-readable spec agents themselves read
• Sessions API — the endpoint behind all of this
• Auth results — exchanging the code