Add AgentID to Auth.js v4

Add AgentID as an OAuth provider to an existing Auth.js v4 or NextAuth.js application. The integration uses discovery, PKCE, state, nonce and explicit ES256 token metadata.

On this page

Recommended: set it up from your project

The CLI finds a supported NextAuth server config, derives its callback, registers AgentID and adds a guarded provider block without replacing the application’s other providers or callbacks. It does not add the sign-in button.

terminal

npx @agentmail/agentid-cli init

The CLI keeps credentials in your project and leaves hosted-provider sign-in disabled until you opt in. See the CLI guide for scope selection, verification and cleanup. The manual steps below remain the fallback.

01Register the callback

Register a confidential client in the AgentID console with the application name and Auth.js callback. The default base path produces this URL:

redirect URI

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

If NEXTAUTH_URL includes a custom auth base path, append /callback/agentid to that complete value instead. Use client_secret_basic for token authentication.

02Store the client credentials

Put the one-time client secret beside the client id in the application environment. Do not expose either value to client-side code.

.env.local

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

03Add the OAuth provider

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

Auth.js provider

{
    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,
        }
    },
}

Watch out. Keep the explicit ES256 client metadata. Auth.js v4 otherwise assumes RS256 even though AgentID discovery advertises ES256, which makes a valid ID token fail verification.

04Offer AgentID sign-in

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

sign-in button

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.

05Check the integration

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

terminal

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.

Watch out. Automatic CLI editing currently supports Auth.js v4. A v5 application can still use AgentID as standard OIDC, but its configuration is outside the CLI-managed path documented here.