Skip to content

secondsky/claude-skills / plugins/better-auth/skills/better-auth

better-auth

Verified

Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.

FileKindSize
SKILL.mdskill md29.2 KB
assets/auth-flow-diagram.mdmarkdown24.0 KB
references/advanced-features.mdmarkdown14.7 KB
references/cloudflare-worker-drizzle.tsscript12.7 KB
references/cloudflare-worker-kysely.tsscript9.7 KB
references/configuration-guide.mdmarkdown10.7 KB
references/database-schema.tsscript10.8 KB
references/databases/mongodb.mdmarkdown5.3 KB
references/databases/mysql.mdmarkdown6.8 KB
references/databases/postgresql.mdmarkdown8.4 KB
references/error-catalog.mdmarkdown12.9 KB
references/framework-comparison.mdmarkdown8.2 KB
references/frameworks/api-frameworks.mdmarkdown9.2 KB
references/frameworks/expo-mobile.mdmarkdown8.7 KB
references/frameworks/nextjs.mdmarkdown5.4 KB
references/frameworks/nuxt.mdmarkdown6.0 KB
references/frameworks/remix.mdmarkdown6.1 KB
references/frameworks/sveltekit.mdmarkdown6.3 KB
references/integrations/electron.mdmarkdown8.2 KB
references/migration-guide-1.4.0.mdmarkdown23.2 KB
references/migration-guide-1.5.0.mdmarkdown6.3 KB
references/nextjs/README.mdmarkdown1.1 KB
references/nextjs/postgres-example.tsscript4.0 KB
references/plugins/api-tokens.mdmarkdown10.0 KB
references/plugins/authentication.mdmarkdown9.2 KB
references/plugins/enterprise.mdmarkdown9.1 KB
references/plugins/payments.mdmarkdown8.0 KB
references/plugins/sso.mdmarkdown9.4 KB
references/plugins/test-utils.mdmarkdown5.5 KB
references/react-client-hooks.tsxother12.8 KB
references/setup-guide.mdmarkdown8.9 KB
references/v1.4-features.mdmarkdown8.2 KB
references/v1.5-features.mdmarkdown11.0 KB
references/v1.6-features.mdmarkdown6.1 KB
scripts/generate-secret.shexecutablescript2.0 KB
scripts/setup-d1-drizzle.shexecutablescript10.2 KB
scripts/test-auth-health.shexecutablescript2.1 KB
scripts/validate-config.tsscript4.3 KB

references/plugins/api-tokens.md

View on GitHub
# better-auth API Token Plugins

Complete guide for API authentication: API Keys, Bearer Tokens, JWT, and OIDC Provider.

---

## API Key Plugin

Extracted to `@better-auth/api-key` in v1.5.0. Install separately:

```bash
npm install @better-auth/api-key
```

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { apiKey } from "@better-auth/api-key";

export const auth = betterAuth({
  plugins: [
    apiKey({
      prefix: "sk_",
      keyLength: 32,
      hashAlgorithm: "sha256",
      rateLimit: {
        window: 60 * 1000,
        max: 100,
      },
    }),
  ],
});
```

### Client Configuration

```typescript
import { apiKeyClient } from "@better-auth/api-key/client";

const authClient = createAuthClient({
  plugins: [apiKeyClient()],
});
```

### Create API Key

```typescript
const { data: key } = await authClient.apiKey.create({
  name: "Production API Key",
  expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
  metadata: {
    environment: "production",
    permissions: ["read", "write"],
  },
});

// IMPORTANT: key.key is only shown once!
console.log(key.key);  // sk_abc123...
```

### Organization-Owned API Keys (v1.5+)

```typescript
import { apiKey } from "@better-auth/api-key";

export const auth = betterAuth({
  plugins: [
    apiKey({ references: "organization" }),
  ],
});

// Create org-owned key
const apiKey = await auth.api.createApiKey({
  body: { organizationId: "org_123" },
});
```

### Multiple Configurations (v1.5+)

```typescript
export const auth = betterAuth({
  plugins: [
    apiKey([
      { configId: "user-keys", prefix: "usr_" },
      { configId: "org-keys", prefix: "org_", references: "organization" },
    ]),
  ],
});

// Create key for specific config
const key = auth.api.createApiKey({
  body: { configId: "user-keys" },
});
```

### List API Keys

```typescript
const { data: keys } = await authClient.apiKey.list();
// Returns key metadata (NOT the actual keys)
```

### Revoke API Key

```typescript
await authClient.apiKey.revoke({
  keyId: "key-id",
});
```

### Use API Key in Requests

```typescript
// Client-side
const response = await fetch("/api/data", {
  headers: {
    "Authorization": `Bearer sk_abc123...`,
  },
});

// Server-side validation
const session = await auth.api.getSession({
  headers: req.headers,
});

if (session?.apiKey) {
  // Request authenticated via API key
  console.log(session.apiKey.name);
  console.log(session.apiKey.metadata);
}
```

---

## Bearer Token Plugin

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { bearer } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    bearer({
      // Token expiration
      expiresIn: 60 * 60 * 24 * 7,  // 7 days
      // Refresh token settings
      refreshToken: {
        enabled: true,
        expiresIn: 60 * 60 * 24 * 30,  // 30 days
      },
    }),
  ],
});
```

### Client Configuration

```typescript
import { bearerClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
  plugins: [bearerClient()],
});
```

### Get Access Token

```typescript
// After sign-in, get bearer token
const { data } = await authClient.signIn.email({
  email: "user@example.com",
  password: "password",
});

// Access token available
const accessToken = data.accessToken;
const refreshToken = data.refreshToken;
```

### Use Bearer Token

```typescript
// API request with bearer token
const response = await fetch("/api/protected", {
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
});
```

### Refresh Token

```typescript
// Refresh when access token expires
const { data } = await authClient.token.refresh({
  refreshToken: refreshToken,
});

const newAccessToken = data.accessToken;
```

---

## JWT Plugin

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { jwt } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    jwt({
      // Signing algorithm
      algorithm: "RS256",  // or HS256, ES256
      // Token expiration
      expiresIn: "1h",
      // Custom claims
      customClaims: async ({ user, session }) => ({
        role: user.role,
        organizationId: session.activeOrganizationId,
      }),
    }),
  ],
});
```

### v1.4.2+ Custom JWKS Endpoint

```typescript
jwt({
  // Custom JWKS endpoint for key rotation
  jwksEndpoint: "/api/auth/.well-known/jwks.json",
  // Key rotation
  keyRotation: {
    enabled: true,
    interval: 60 * 60 * 24 * 7,  // 7 days
  },
}),
```

### Client Configuration

```typescript
import { jwtClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
  plugins: [jwtClient()],
});
```

### Get JWT

```typescript
// Get JWT for current session
const { data } = await authClient.jwt.getToken();
const jwt = data.token;
```

### Verify JWT (Server-Side)

```typescript
import { jwtVerify } from "jose";

// Get public key from JWKS endpoint
const response = await fetch("https://your-app.com/api/auth/.well-known/jwks.json");
const jwks = await response.json();

// Verify token
const { payload } = await jwtVerify(token, createRemoteJWKSet(
  new URL("https://your-app.com/api/auth/.well-known/jwks.json")
));

console.log(payload.sub);  // User ID
console.log(payload.role);  // Custom claim
```

### JWT for External Services

```typescript
// Generate JWT for third-party API
const { data } = await authClient.jwt.getToken({
  audience: "https://external-api.com",
  scope: "read:data write:data",
});
```

---

## OIDC Provider (DEPRECATED in v1.6 — use `@better-auth/oauth-provider`)

Make your app an OpenID Connect provider for other applications.

> **v1.6+**: The built-in `oidcProvider` plugin is deprecated and slated for
> removal in the next minor. Migrate to the dedicated
> `@better-auth/oauth-provider` package, which turns your instance into a full
> OAuth 2.1 / OIDC authorization server.

### Recommended: `@better-auth/oauth-provider` (v1.5+)

```bash
npm install @better-auth/oauth-provider
```

```typescript
import { betterAuth } from "better-auth";
import { oauthProvider } from "@better-auth/oauth-provider";

export const auth = betterAuth({
  plugins: [
    oauthProvider({
      // OIDC issuer URL
      issuer: "https://your-app.com",
    }),
  ],
});
```

### Legacy: `oidcProvider` (deprecated, removed soon)

```typescript
import { betterAuth } from "better-auth";
import { oidcProvider } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    oidcProvider({
      // OIDC issuer URL
      issuer: "https://your-app.com",
      // Registered clients
      clients: [
        {
          clientId: "client-app-1",
          clientSecret: "secret",
          redirectUris: ["https://client-app.com/callback"],
          scopes: ["openid", "profile", "email"],
        },
      ],
      // Supported scopes
      scopes: ["openid", "profile", "email", "offline_access"],
      // Token settings
      accessTokenTTL: 60 * 60,  // 1 hour
      refreshTokenTTL: 60 * 60 * 24 * 30,  // 30 days
    }),
  ],
});
```

### v1.4.8+ OAuth 2.1 Compliance

```typescript
import { oauth21 } from "better-auth/plugins";

oidcProvider({
  // Enable OAuth 2.1 compliant mode
  oauth21: true,
  // Require PKCE for all clients
  requirePKCE: true,
}),
```

### OIDC Endpoints

Automatically created endpoints:

| Endpoint | Description |
|----------|-------------|
| `/.well-known/openid-configuration` | Discovery document |
| `/api/auth/oauth/authorize` | Authorization endpoint |
| `/api/auth/oauth/token` | Token endpoint |
| `/api/auth/oauth/userinfo` | UserInfo endpoint |
| `/api/auth/oauth/jwks` | JWKS endpoint |
| `/api/auth/oauth/revoke` | Token revocation |

### Client App Integration

```typescript
// In client application
const authUrl = new URL("https://your-app.com/api/auth/oauth/authorize");
authUrl.searchParams.set("client_id", "client-app-1");
authUrl.searchParams.set("redirect_uri", "https://client-app.com/callback");
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", "openid profile email");
authUrl.searchParams.set("state", generateState());
authUrl.searchParams.set("code_challenge", codeChallenge);  // PKCE
authUrl.searchParams.set("code_challenge_method", "S256");

// Redirect user to authUrl
```

### Consent Screen Customization

```typescript
oidcProvider({
  // Custom consent page
  consentPage: "/oauth/consent",
  // Skip consent for first-party apps
  skipConsentForFirstParty: true,
}),
```

---

## Combining Token Plugins

```typescript
import { betterAuth } from "better-auth";
import { apiKey } from "@better-auth/api-key";
import { bearer, jwt, oidcProvider } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    // API keys for server-to-server
    apiKey({
      prefix: "sk_",
      rateLimit: { window: 60000, max: 100 },
    }),
    // Bearer tokens for mobile apps
    bearer({
      expiresIn: 60 * 60 * 24 * 7,
      refreshToken: { enabled: true },
    }),
    // JWT for microservices
    jwt({
      algorithm: "RS256",
      expiresIn: "1h",
    }),
    // OIDC for third-party apps
    oidcProvider({
      issuer: "https://your-app.com",
      clients: [/* ... */],
    }),
  ],
});
```

---

## Common Issues

### API Key: "Invalid API key"
- Keys are hashed - original key only shown once on creation
- Check prefix matches configured prefix
- Verify key hasn't been revoked

### Bearer: "Token expired"
- Implement token refresh flow
- Check client timezone vs server timezone

### JWT: "Invalid signature"
- Verify JWKS endpoint is accessible
- Check algorithm matches (RS256 vs HS256)
- Key rotation may have occurred - refetch JWKS

### OIDC: "Invalid redirect_uri"
- Exact match required (including trailing slash)
- Register all redirect URIs in client config

### OIDC: "PKCE required"
- OAuth 2.1 mode requires PKCE
- Generate code_verifier and code_challenge on client

---

## Official Resources

- API Key: https://better-auth.com/docs/plugins/api-key
- Bearer Token: https://better-auth.com/docs/plugins/bearer
- JWT: https://better-auth.com/docs/plugins/jwt
- OIDC Provider: https://better-auth.com/docs/plugins/oidc-provider
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall