secondsky/claude-skills / plugins/better-auth/skills/better-auth
better-auth
VerifiedSkill 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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |