Quick start

Create an app on Dashboard → Developer first. Copy the client ID, and the client secret if you picked Web app with a server (it is shown once). Register the redirect URI your library uses.

Better Auth

If your app already uses Better Auth, the genericOAuth plugin does everything from discovery:

import { betterAuth } from "better-auth"
import { genericOAuth } from "better-auth/plugins"

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [{
        providerId: "osintverse",
        discoveryUrl: "https://osintverse.com/api/auth/.well-known/openid-configuration",
        clientId: process.env.OSINTVERSE_CLIENT_ID!,
        clientSecret: process.env.OSINTVERSE_CLIENT_SECRET!,
        scopes: ["openid", "profile", "email"],
        pkce: true,
      }],
    }),
  ],
})

Redirect URI to register: https://your-app.com/api/auth/oauth2/callback/osintverse. On the client, add genericOAuthClient() and call:

await authClient.signIn.oauth2({ providerId: "osintverse", callbackURL: "/" })

Auth.js

import NextAuth from "next-auth"

export const { handlers, auth, signIn } = NextAuth({
  providers: [{
    id: "osintverse",
    name: "OSINTverse",
    type: "oidc",
    issuer: "https://osintverse.com/api/auth",
    clientId: process.env.OSINTVERSE_CLIENT_ID,
    clientSecret: process.env.OSINTVERSE_CLIENT_SECRET,
    checks: ["pkce", "state"],
  }],
})

Redirect URI to register: https://your-app.com/api/auth/callback/osintverse.

Any OIDC library

The flow is the standard authorization code flow with PKCE:

1. Send the person to the authorization_endpoint with response_type=code, your client_id, redirect_uri, scope=openid profile email, a state, and an S256 code_challenge.
2. On your redirect URI, exchange the code at the token_endpoint with the code_verifier (and your client secret for web apps, sent as HTTP Basic).
3. Verify the id_token against the JWKS (issuer https://osintverse.com/api/auth, audience your client ID, algorithm EdDSA), or call the userinfo_endpoint with the access token.

Use sub as the stable user id. Email addresses can change.

Testing on localhost

While your app is in testing, http://localhost and http://127.0.0.1 redirect URIs are allowed. Approved web apps must use https; keep a separate app for local development.

Signing out

Clearing your own session is enough for most apps. To also end the OSINTverse session, send the person to the end_session_endpoint from discovery with id_token_hint and a registered post-logout redirect URI.