ChaiAuth docs ยท v1

Add sign-in to your app in minutes.

ChaiAuth is an OpenID Connect provider. Passkeys, two-factor auth, sessions and consent all run on our UI. Your app just speaks standard OIDC.

Quick start

Three steps from zero to a signed-in user.

STEP 01

Create an app

Register your name and callback URL in the console.

STEP 02

Redirect to sign-in

Send users to /authorize with state and a PKCE challenge.

STEP 03

Exchange the code

Swap the code for tokens on your server.

Configure your app

Create credentials in the developer console. Redirect URIs must use HTTPS (http is allowed only for localhost) and are matched exactly.

SettingExample
Client IDca_live_8f2k1m9qz4
App URLhttps://yourapp.com
Redirect URIhttps://yourapp.com/auth/callback
Scopesopenid profile email

Auth.js / NextAuth

ChaiAuth publishes an OpenID discovery document, so Auth.js finds the token, userinfo and JWKS endpoints by itself.

terminal
npm install next-auth
app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";

export const authOptions = {
  providers: [
    {
      id: "chaiauth",
      name: "ChaiAuth",
      type: "oauth",
      wellKnown: "https://auth-api.kenilpatel.in/.well-known/openid-configuration",
      clientId: process.env.CHAIAUTH_CLIENT_ID,
      clientSecret: process.env.CHAIAUTH_CLIENT_SECRET,
      authorization: { params: { scope: "openid profile email" } },
      idToken: true,
      checks: ["pkce", "state"],
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
        };
      },
    },
  ],
};

export default NextAuth(authOptions);
Using another library? Point it at https://auth-api.kenilpatel.in/.well-known/openid-configuration and use the Authorization Code flow with PKCE.

Authorization flow

Send the browser to the sign-in and consent screen. Generate a fresh state and PKCE pair for every request.

authorization request
https://chaiauth.kenilpatel.in/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &scope=openid profile email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
Preview consent screen

Token exchange

Do this on your server so the client secret never reaches the browser. Public clients (SPA / mobile) skip client_secret and rely on PKCE.

POST /o/token
# Exchange the code for tokens (server side)
curl -X POST https://auth-api.kenilpatel.in/o/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/auth/callback" \
  -d "code_verifier=YOUR_PKCE_VERIFIER"
response
{
  "access_token": "eyJhbGciOi...",
  "id_token": "eyJhbGciOi...",
  "refresh_token": "a1b2c3...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}
Use grant_type=refresh_token with your refresh token to get new access tokens.

React SDK

@chaiauth/react runs the whole flow for you: PKCE, state and nonce checks, token refresh and sign-out, with ready-made components.

providers.tsx
"use client";
import { ChaiAuthProvider } from "@chaiauth/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ChaiAuthProvider
      clientId={process.env.NEXT_PUBLIC_CHAIAUTH_CLIENT_ID!}
      redirectUri="https://yourapp.com/auth/callback" // exactly as registered
      issuer="https://auth-api.kenilpatel.in"
    >
      {children}
    </ChaiAuthProvider>
  );
}
header.tsx
import { SignIn, SignedIn, SignedOut, UserButton, useChaiAuth } from "@chaiauth/react";

export function Header() {
  return (
    <header>
      <SignedOut>
        <SignIn returnTo="/dashboard" />
      </SignedOut>
      <SignedIn>
        <UserButton accountUrl="https://chaiauth.kenilpatel.in/dashboard" />
      </SignedIn>
    </header>
  );
}

// Calling your own backend with the user's access token
export function useApi() {
  const { getAccessToken } = useChaiAuth();
  return async (path: string) => {
    const token = await getAccessToken(); // refreshed automatically when needed
    return fetch(path, { headers: { Authorization: `Bearer ${token}` } });
  };
}
The SDK uses PKCE, so your client secret is never needed in the browser. The provider finishes sign-in on whatever page your redirect URI points to, so that page only has to render inside <ChaiAuthProvider>. The package lives in this repo (packages/react) until it is published to npm.

Endpoints

Base URL: https://auth-api.kenilpatel.in

GET/.well-known/openid-configurationOpenID provider metadata
GET/.well-known/jwks.jsonPublic keys to verify ID tokens (RS256)
GET/o/authorizeValidate an authorization request
POST/o/tokenExchange a code or refresh token for tokens
GET/o/userinfoRead approved profile claims (Bearer token)
POST/o/revokeRevoke a token
GET/v1/usersList users who granted your app access (API key)
GET/v1/users/:userIdRead one user's approved claims (API key)

Scopes & claims

Request only what you need. Unsupported scopes are ignored; a request with no supported scope is rejected.

openid

Required for OIDC. Returns an ID token with the sub claim.

profile

The user's name.

email

The user's email and email_verified.

Server API & keys

Create an API key in the developer console (open your app, then API keys) to call ChaiAuth from your own backend, without a user present.

terminal
# List the users who granted your app access
curl "https://auth-api.kenilpatel.in/v1/users?limit=20" \
  -H "Authorization: Bearer ca_live_YOUR_API_KEY"

# One user
curl "https://auth-api.kenilpatel.in/v1/users/USER_ID" \
  -H "Authorization: Bearer ca_live_YOUR_API_KEY"
GET /v1/users/:userId
{
  "success": true,
  "data": {
    "sub": "8f14e45f-ceea-4f67-9c1e-2b9d3a6b1c7e",
    "name": "Asha Patel",
    "email": "asha@example.com",
    "email_verified": true,
    "scope": "openid profile email",
    "granted_at": "2026-11-09T10:15:00.000Z"
  }
}
Keys are shown once, stored only as a hash, can expire, and can be revoked at any time. You can read only users who approved your app, and only the claims their consent covers. Each key is limited to 120 requests per minute.

Security notes

  • Use PKCE (S256) for every public client and single-page application.
  • Generate and validate a unique state value for every request.
  • Keep client secrets on your server. Never expose them in browser code.
  • Use exact redirect URI matching and HTTPS in production.
  • Verify ID tokens against the JWKS endpoint before trusting them.
  • Treat API keys like passwords: server side only, one per service, revoke on suspicion.