---
name: sign-in-with-oversine
description: Add "Sign in with Oversine" to a web app so people and their AI agents can sign in or sign up. Use when asked to integrate Oversine, add Oversine login, support agent sign-in, or connect an app to the Oversine OpenID Connect provider.
---

# Add "Sign in with Oversine"

Oversine is an OpenID Connect provider: "Sign in with Google", except that a person's AI agent can
sign in as them too. Your app integrates it as a standard OIDC relying party. Any OIDC library
works and there is no SDK. Two things make the integration visible to agents, and this skill adds
both: a button labelled exactly "Sign in with Oversine", and a visually hidden description of what
the site supports.

Oversine origin: `https://auth.oversine.com`

Every Oversine URL below is on that origin. If it still reads as a placeholder, ask the developer
for their Oversine origin before continuing.

## 1. Register the app

Register it yourself at `https://auth.oversine.com/dashboard`: sign in with Oversine, choose "Register a platform",
and enter your redirect URI (for example `https://app.example.com/api/auth/callback/oversine`).
Pick the client type:

- server-rendered app: gets a `client_secret` (authentication method `client_secret_basic`);
- single-page or native app: a public client (method `none`) with no secret.

PKCE is required either way. The platform's page shows its `client_id`, the `client_secret` for
server-side apps, and later its sign-in stats. If someone else registered the app for you, ask
them for those values.

Keep these in environment variables, and keep the secret server-side only:

```
OVERSINE_ISSUER=https://auth.oversine.com
OVERSINE_CLIENT_ID=...
OVERSINE_CLIENT_SECRET=...   # server-side apps only
```

## 2. Configure the OIDC client

Point your OIDC library at the issuer and let discovery fill in the endpoints:

- Discovery: `https://auth.oversine.com/.well-known/openid-configuration`
- Flow: authorization code with PKCE (S256). Checks: `pkce`, `state`, `nonce`.
- Scopes: `openid profile email`
- Optional: request the `amr` claim to learn whether an agent signed in. Pass the OIDC `claims`
  parameter as `{"id_token":{"amr":null}}`; an agent sign-in carries `amr: ["agent"]`.

Auth.js (Next.js) example, which is the shape of the reference demo:

```ts
import NextAuth from "next-auth";

export const issuer = (process.env.OVERSINE_ISSUER ?? "https://auth.oversine.com").replace(/\/$/, "");

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: "oversine",
      name: "Oversine",
      type: "oidc",
      issuer,
      clientId: process.env.OVERSINE_CLIENT_ID,
      clientSecret: process.env.OVERSINE_CLIENT_SECRET,
      authorization: {
        params: {
          scope: "openid profile email",
          // Pass an object, not a string: Auth.js serialises it once.
          claims: { id_token: { amr: null } },
        },
      },
      checks: ["pkce", "state", "nonce"],
      profile(p) {
        return { id: p.sub, name: p.name ?? null, email: p.email ?? null, image: p.picture ?? null };
      },
    },
  ],
});
```

With any other library, use the same issuer, scopes, PKCE, and `claims` parameter.

## 3. Add the button

On every page where a person can sign in or sign up, add a button labelled exactly
**Sign in with Oversine** (use **Sign up with Oversine** on a dedicated sign-up page). Clicking it
starts the OIDC authorization request. People and agents both click this same button; the Oversine
page it opens handles the rest, so the button needs nothing agent-specific.

## 4. Add the hidden description

Once on every page that offers the button (anywhere in the page, the top is fine), add this
element. It is visually hidden but stays in the accessibility tree, which is what agents read. Keep
the wording as written, and use clip-based hiding as shown; `display:none` or `hidden` would remove
it from the tree.

Plain HTML:

```html
<p data-oversine-description style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0">
This site supports Sign in with Oversine, a sign-in identity for people and their AI agents. An agent whose user has connected the Oversine MCP signs in by clicking the "Sign in with Oversine" button and approving the request code shown on the Oversine page that opens. An agent whose user has not connected Oversine yet points them to the one-time setup at https://auth.oversine.com/setup.
</p>
```

React (Tailwind's `sr-only` is clip-based):

```tsx
<p data-oversine-description className="sr-only">
  This site supports Sign in with Oversine, a sign-in identity for people and their AI agents. An
  agent whose user has connected the Oversine MCP signs in by clicking the &quot;Sign in with Oversine&quot;
  button and approving the request code shown on the Oversine page that opens. An agent whose user
  has not connected Oversine yet points them to the one-time setup at {issuer}/setup.
</p>
```

The text describes what the site supports and where setup lives. The steps an agent follows come
from the Oversine MCP it has installed, so the page never needs to instruct it.

## 5. Create accounts on first sign-in

Find or create your user by the ID token's `sub` (stable Oversine user id); take `email` and
`name` from the ID token or the userinfo endpoint. A first sign-in creates the account, which is
also how an agent signs a person up: there is no separate sign-up flow. If you requested `amr`,
store or display whether the session was opened by an agent.

## 6. Verify

- Person: click the button, sign in on the Oversine page, land back in your app signed in.
- Agent: connect the Oversine MCP in an agent host that has a browser (steps at
  `https://auth.oversine.com/setup`), then ask the agent to sign in to your app. It clicks the button, approves the
  code through the MCP, and the page returns signed in.