Add AgentID to Auth.js v4

In the AgentID console, click Create application. Choose Other / custom integration as the auth provider and enter your app name. Use this redirect URI:

https://yourapp.com/api/auth/callback/agentid

If NEXTAUTH_URL includes a custom auth path, add /callback/agentid to the end of it instead. Leave the token endpoint auth method as client_secret_basic, then click Create application.

Copy the Client ID and Client secret into your server environment. The secret is shown only once. Never send either value to the browser.

AGENTID_CLIENT_ID=<client id>
AGENTID_CLIENT_SECRET=<client secret>

Add this entry to the existing providers array passed to NextAuth:

{
    id: "agentid",
    name: "AgentID",
    type: "oauth",
    wellKnown: "https://auth.agentid.com/.well-known/openid-configuration",
    authorization: { params: { scope: "openid email profile" } },
    idToken: true,
    checks: ["pkce", "state", "nonce"],
    client: { id_token_signed_response_alg: "ES256" },
    clientId: process.env.AGENTID_CLIENT_ID!,
    clientSecret: process.env.AGENTID_CLIENT_SECRET!,
    profile(profile) {
        return {
            id: profile.sub,
            name: profile.name,
            email: profile.email,
            image: profile.picture ?? null,
        }
    },
}

Auth.js does not add a provider button to the application. Call the existing v4 client helper from your sign-in UI:

import { signIn } from "next-auth/react"

await signIn("agentid")

To request owner information, add owner_profile or owner_email to the scope string. Persisting those raw OAuth profile values in a JWT, session, adapter or custom user field is application-specific.

Don’t want a visible AgentID button? See step 5.

Don’t want a visible AgentID button? Add a page that calls the step 4 helper as soon as it loads.

Agents connect to your app from AgentMail by opening its initiate login URI. A sign-in page with your AgentID button works as one: AgentID tells the agent to choose AgentID there.

'use client'

import { signIn } from "next-auth/react"
import { useEffect, useRef } from "react"

export default function AgentIdSignIn() {
    const started = useRef(false)

    useEffect(() => {
        if (started.current) return // effects can run more than once
        started.current = true
        void signIn("agentid")
    }, [])

    return null
}

Then open your application in the AgentID console, choose Settings › Edit, and paste the page’s address into Initiate login URL, for example https://yourapp.com/login/agentid, or your sign-in page’s if you kept the button. Click Save changes.

Start with the read-only CLI check, then exercise the application button:

npx @agentmail/agentid-cli doctor

A working sign-in returns through /api/auth/callback/agentid, verifies the AgentID ID token and gives Auth.js the agent’s stable subject, inbox email and display name.