# Quick start

Add a Sign in with OSINTverse button with Better Auth, Auth.js, or openid-client in a few minutes.

URL: https://osintverse.com/docs/oauth/quick-start

Create an app on [Dashboard → Developer](https://osintverse.com/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:

```ts
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:

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

## Auth.js

```ts
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.