> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Versine works

> How an agent signs in and what each party verifies.

Versine lets AI agents sign in to and sign up for platforms as their user. It
sits between two parties:

* **Assistants**, the companies that run agents. They already know who their
  user is and have verified that user's email.
* **Platforms**, which add **Are you an agent?** to their login and sign-up
  pages. They connect Versine to their existing auth as an OpenID Connect
  (OIDC) provider, like any other sign-in option.

Versine works in the background. End users never sign up for it, open it or
see it: they use their assistant, and their agent signs in to the platform.

## A sign-in

```mermaid theme={null}
sequenceDiagram
  participant B as Agent's browser
  participant P as Platform
  participant V as auth.versine.com
  participant A as Assistant
  B->>P: Click "Are you an agent?"
  P-->>B: Redirect to Versine /authorize
  B->>A: Ask to sign in at this URL
  A->>V: Request a sign-in token, with the user's details
  V-->>A: Token (60 seconds, single use, this URL only)
  A-->>B: Token
  B->>V: /authorize with Versine-Sign-In header
  V-->>B: Redirect back with an authorization code
  B->>P: Callback
  P->>V: Exchange the code for an ID token
  V-->>P: ID token
  P-->>B: Signed in
```

1. The agent clicks **Are you an agent?** The platform starts an ordinary OIDC
   sign-in and redirects the browser to Versine.
2. The assistant's browser recognizes the Versine sign-in URL. The assistant
   gets its user's approval in whatever way suits its product.
3. The assistant's backend tells Versine who the user is. Versine checks the
   platform's policy and returns a one-time **sign-in token** for that exact
   URL. The browser sends it to Versine in a
   `Versine-Sign-In` header.
4. Versine redeems the token and redirects straight back to the platform. The
   agent never sees a code, a password or a Versine page.
5. The platform's auth provider exchanges the code for an ID token, then signs
   the agent in to an existing account or creates a new one.

Agents whose browser can't add headers can instead type in a
[one-time code](/docs/assistants#use-a-code-instead-of-a-header) from their
assistant, if the platform allows it.

## What each party checks

| Party | Checks |
| - | - |
| Assistant | Its user is happy to share the requested details with this platform, in whatever way the assistant asks |
| Versine | The assistant's credentials, and that the platform accepts it; the token is unused, unexpired and for this exact sign-in |
| Platform | The ID token, as from any OIDC provider; which account the sign-in belongs to; what agents may do |

## Identity

* **Subject:** each person gets a `sub` that is stable for one platform and one
  assistant. Platforms can't correlate users with each other through it. The
  same person signing in through two different assistants has two subjects,
  which the platform joins by email or phone number.
* **Email and phone number:** the assistant reports how and when it verified
  each. Versine marks an email verified if that was within the last year, and a
  phone number within the last 30 days, and passes the details on to the
  platform. An assistant end users text from their phone re-verifies the number
  with every message.
* **Assistant:** every token names the assistant in
  `https://versine.com/claims/assistant`, and has `amr: ["agent"]`.

See [connect user accounts](/docs/platforms#4-connect-user-accounts) for how
platforms use these claims.

## Security properties

* **No reusable credentials:** sign-in tokens last 60 seconds, work once, and
  only for the URL they were made for. Versine holds every signing key, so
  assistants have none to manage or leak.
* **Can't be relayed:** the identity travels in a header from the agent's own
  browser. Only that browser can complete the sign-in, because the platform's
  auth provider checks its own `state` cookie on return.
* **Only what's requested:** Versine releases only the details a platform asked
  for. Assistants decide how their users approve sharing them.
* **Platforms choose assistants:** each platform decides which assistants it
  accepts. Versine reviews every assistant, can suspend one or revoke its
  credentials immediately, and keeps a record of every sign-in it requests.
* **One destination:** assistants send identity only to
  `auth.versine.com/authorize`, only when signing in. Websites never receive a
  header saying the visitor is an agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.