# Civic Auth Setup Reference

Docs: https://docs.civic.com/auth
Dashboard: https://auth.civic.com

Civic Auth is a drop-in authentication SDK. Google, Apple, email, and passkey sign-in are built in. After login, agents get scoped Civic tokens with audit trails and instant revocation.

**NPM packages:**
- `@civic/auth` — base auth SDK (JS/TS)
- `@civic/auth-web3` — with Web3 wallet support
- `civic-auth` — Python package (pip/uv)

## Next.js (recommended)

Docs: https://docs.civic.com/integration/nextjs

Requires Next.js ^14.2.25 or ^15.2.3+.

```bash
npm install @civic/auth
```

**1. next.config.ts:**
```typescript
import { createCivicAuthPlugin } from "@civic/auth/nextjs"
import type { NextConfig } from "next";
const nextConfig: NextConfig = {};
const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID"
});
export default withCivicAuth(nextConfig)
```

**2. src/app/api/auth/[...civicauth]/route.ts:**
```typescript
import { handler } from "@civic/auth/nextjs"
export const GET = handler()
export const POST = handler()
```

**3. src/middleware.ts:**
```typescript
import { authMiddleware } from "@civic/auth/nextjs/middleware"
export default authMiddleware();
export const config = {
  matcher: [
    '/((?!_next|favicon.ico|sitemap.xml|robots.txt|.*\\.jpg|.*\\.png|.*\\.svg|.*\\.gif).*)',
  ],
}
```

**4. Layout:** Wrap with `CivicAuthProvider` from `@civic/auth/nextjs`.

**Server-side usage:**
```typescript
import { getUser } from "@civic/auth/nextjs";
const user = await getUser();
```

```typescript
import { getTokens } from "@civic/auth/nextjs";
const { accessToken } = await getTokens();
```

**Config options:**

| Parameter | Required | Default |
|-----------|----------|---------|
| `clientId` | Yes | — |
| `loginSuccessUrl` | No | — |
| `callbackUrl` | No | `/api/auth/callback` |
| `loginUrl` | No | `/` |
| `logoutUrl` | No | `/` |
| `include` | No | `["/*"]` |
| `exclude` | No | — |

**Environment variable:** `CIVIC_AUTH_CLIENT_ID`

## React

```bash
npm install @civic/auth
```

Wrap your app with the Civic Auth provider and use the auth hook for sign-in state.

## React Native

```bash
npm install @civic/auth
```

Same provider pattern as React, adapted for native navigation.

## Node.js / Express

```bash
npm install @civic/auth
```

Use as middleware to validate Civic tokens on API routes.

## Python (Django / FastAPI / Flask)

```bash
pip install civic-auth
# or:
uv add civic-auth
```

Civic Auth provides a standard OIDC flow. Use the REST endpoints or the Python SDK for per-user token management in web apps.

## Starter Template

Full working Next.js app with Civic Auth + Vercel AI SDK + MCP:

```bash
git clone https://github.com/civicteam/ai-chatbot.git
cd ai-chatbot
pnpm install
cp .env.example .env.local
# Set CIVIC_AUTH_CLIENT_ID in .env.local
pnpm dev
```

## Token Exchange (advanced)

If your users already sign in with Google, Auth0, Azure AD, or Okta, Token Exchange converts those tokens into Civic tokens via a single POST request using standard OAuth 2.0 Token Exchange (RFC 8693). No re-authentication, no login screen changes.