---
id: JosiahSiegel/claude-plugin-marketplace/clerk-backend-apis
version: "b0dbe141"
license: MIT
install: manual
updated: 2026-06-18
---

# clerk-backend-apis — This skill guides you through authenticating and authorizing incoming requests on backend services using Clerk's SDKs and middleware. It covers request flow, token verification, cross-origin patterns, proxy header preservation, and Backend API client usage across Node, Go, Python, Ruby, Java, C#, and PHP frameworks.

Publisher: JosiahSiegel · Stars: 49 · Updated: 2026-06-18

Install (manual): `git clone https://github.com/JosiahSiegel/claude-plugin-marketplace`

## SKILL.md

# Clerk Backend APIs

## Overview

Use this skill for Clerk authentication in backend services, API servers, workers, and server-to-server integrations. The key responsibilities are authenticating incoming requests, enforcing authorization on server resources, safely using the Backend API, and making cross-origin token behavior explicit.

Prefer official Clerk SDKs and middleware when available. When the target runtime lacks a first-class Clerk framework SDK, use Clerk-documented token verification and Backend API patterns rather than ad hoc JWT parsing.

## Backend Integration Model

The server flow is language-independent:

1. Receive request.
2. Preserve auth-relevant headers and cookies through all proxies.
3. Authenticate Clerk input using an official SDK/helper where available.
4. Derive identity, session, organization, and token type from verified request state.
5. Authorize the requested resource and action.
6. Parse/validate application input.
7. Perform data access or side effects.
8. Return explicit `401` unauthenticated or `403`/concealment unauthorized responses for APIs, unless using Clerk defaults intentionally.

Avoid handwritten JWT parsing unless Clerk's official docs for the target language require a lower-level path. Clerk token semantics evolve, and framework SDKs handle edge cases better than custom code.

## Express Pattern

Register Clerk middleware before routes that need auth state. Use `getAuth(req)` in route handlers when custom JSON responses are preferred. Use `requireAuth()` when automatic route protection behavior fits the app.

Minimal shape:

```ts
import express from 'express'
import { clerkMiddleware, getAuth, requireAuth } from '@clerk/express'

const app = express()
app.use(clerkMiddleware())

app.get('/api/me', (req, res) => {
  const { isAuthenticated, userId, orgId } = getAuth(req)
  if (!isAuthenticated) return res.status(401).json({ error: 'Unauthorized' })
  return res.json({ userId, orgId })
})

app.get('/api/protected', requireAuth(), (req, res) => {
  res.json({ ok: true })
})
```

`clerkMiddleware()` checks request cookies and headers for a session JWT and attaches auth state to the request. `getAuth(req)` reads user ID, session ID, organization ID, and related auth state. `clerkClient` wraps Clerk's Backend API and must be instantiated according to the SDK's current docs before resource access.

## Fastify Pattern

Use Clerk's Fastify plugin where available. The documented model is:

- Register `clerkPlugin()` with the Fastify app before protected routes.
- The plugin checks request cookies and headers for a session JWT.
- Valid auth data is attached to `request.auth`.
- Use `getAuth(request)` to retrieve current auth state.
- Use `clerkClient` server-side for Backend API calls after instantiation.

If the framework integration does not expose `requireAuth()`, implement route guards with `getAuth(request)` and explicit JSON responses.

## Cross-Origin Requests

Same-origin browser requests in supported Clerk frameworks can often rely on Clerk-managed cookies. Cross-origin requests to a separate API origin must include a Bearer token retrieved from the frontend session.

Client pattern:

```js
const token = await getToken()
await fetch('https://api.example.com/widgets', {
  headers: { Authorization: `Bearer ${token}` },
})
```

Backend pattern:

- Accept the `Authorization` header.
- Ensure CORS allows the exact frontend origin and the `Authorization` header.
- Authenticate the token with Clerk middleware or documented backend helper.
- Reject missing, invalid, expired, wrong-environment, or wrong-token-type requests before touching application data.

Common mistakes: forgetting to await `getToken()`, relying on cookies across origins, stripping `Authorization` in a proxy, wildcard CORS with credentials, and debugging only browser navigations instead of direct API requests.

## Request State and Proxy Headers

Clerk uses request headers to determine whether a request is signed in, signed out, or needs a handshake. Behind proxies, CDNs, and load balancers, preserve auth-relevant headers.

Required/important headers include:

- `Authorization`
- `Accept`
- `Host`
- `Origin`
- `Referer`
- `Sec-Fetch-Dest`
- `User-Agent`
- `X-Forwarded-Host`
- `X-Forwarded-Proto` or `CloudFront-Forwarded-Proto`

When deploying behind CloudFront, Nginx, Vercel rewrites, Cloudflare, custom domains, API gateways, or Kubernetes ingress, test the exact production path. Local success does not prove forwarded headers survive production.

## Backend API Client Guardrails

Use Clerk's Backend API client only from trusted server environments. Typical operations include fetching users, listing users, updating metadata, reading organizations, and managing memberships. Never expose Backend API credentials, secret keys, or administrative operations to browser code.

Instantiate the client according to the SDK's current docs before accessing resources. Avoid manual fetches to Clerk's API unless the SDK lacks the needed feature or the docs explicitly recommend direct API calls.

Use Backend API calls sparingly in hot paths. For high-traffic endpoints, prefer auth IDs from request state and store app-specific data in the application's database. Use webhooks for asynchronous denormalization when appropriate.

## Language-Portable Backend Patterns

### Node/Express/Fastify

Use official Clerk middleware/plugins. Keep `CLERK_SECRET_KEY` on the server. Use `getAuth()`/request auth state for identity and org context. Use `clerkClient` only after authorization when calling administrative APIs.

### Go

Use Clerk's Go SDK or documented verification helpers if present for the project. If integrating manually, treat the process as verifying a Clerk-issued JWT against Clerk's documented issuer/JWKS/audience rules and extracting claims only after verification. Do not trust decoded claims without signature, issuer, audience, expiration, and token-type validation. Wrap the verification in middleware and attach a typed auth context to `context.Context` for handlers.

### Python/FastAPI, Django, Flask

Use a request middleware/dependency/decorator pattern:

- Extract `Authorization: Bearer <token>` or documented Clerk cookie/header inputs.
- Verify with Clerk SDK/helpers or documented JWT/JWKS process.
- Attach user/session/org/token-type state to `request.state`, dependency return value, or framework context.
- Enforce authorization in dependencies/decorators before executing route logic.
- Keep Backend API secret keys in environment variables read only by the server process.

For FastAPI, prefer dependency injection for protected routes. For Django/Flask, prefer middleware plus decorators/blueprint guards.

### Ruby/Rails

Use middleware or controller concerns before actions. Verify Clerk tokens with official SDK/helpers or documented JWT verification. Store verified auth state in request env/current context. Do not use params for user/org IDs. Use Rails credentials or server environment variables for Clerk secrets, not frontend packs/assets.

### Java/Spring

Use a servlet filter or Spring Security authentication provider. Verify Clerk tokens before controllers execute and populate the SecurityContext with a principal containing Clerk user ID, session ID, org ID, and token type. Use method-level authorization or service-layer checks for roles/org resources. Externalize keys/secrets with environment or secret manager configuration.

### C#/.NET/ASP.NET Core

Use authentication middleware/JWT bearer configuration or a custom authentication handler aligned with Clerk's token verification docs. Populate `ClaimsPrincipal` only after issuer/audience/signature/expiration checks. Use authorization policies for org/role/permission checks. Keep secret keys in user secrets for local development and managed secret stores for production.

### PHP/Laravel

Use HTTP middleware to verify Clerk tokens before controllers. Attach verified auth state to the request/container/auth guard. Use policies/gates for resource authorization. Store Clerk server credentials in `.env`/secret manager and never expose them through frontend build variables.

## Authorization Patterns

Authentication answers “who or what made this request.” Authorization answers “may this identity do this action on this resource.” Enforce both.

Recommended checks:

- Compare `userId`/subject to resource ownership for personal resources.
- Compare active organization ID to the resource organization for org-scoped resources.
- Check roles or custom permissions for admin actions.
- Require the correct token type for machine, OAuth, API-key, and human session flows.
- Verify plan/feature entitlements server-side before protected operations.
- Default-deny unknown roles, absent org context, pending sessions, and unsupported token types.

Do not trust user IDs, organization IDs, roles, plan values, or permissions submitted in request bodies. Derive them from the Clerk-authenticated request state or verified server-side records.

## Machine, OAuth, API-Key, and Session Token Flows

Design service-to-service endpoints separately from browser-session endpoints. Decide whether the endpoint accepts session tokens, machine-to-machine tokens, OAuth access tokens, API keys, or any of them. In Next.js, `auth.protect()` supports token-type checks; in other backends, follow equivalent Clerk docs for accepted token validation.

Recommended endpoint design:

- Human user APIs: accept session tokens, require `userId`, optionally require `orgId`.
- Service APIs: accept M2M/API-key tokens, reject browser session tokens unless explicitly needed.
- OAuth resource APIs: accept OAuth access tokens and validate scopes/audience as documented.
- Admin APIs: require strongest token type plus role/permission checks and audit logging.

Return clear failure codes. Browser session flows may redirect, but API and machine flows should return JSON with `401` for unauthenticated requests and `403` or intentional concealment for unauthorized requests, unless using Clerk defaults that intentionally return `404`.

## Webhook Endpoints in Backends

Webhook endpoints are not authenticated user requests. Exempt them from session middleware protection, then verify Svix signatures with Clerk's `verifyWebhook()` helper or Svix verification libraries before trusting payloads. Do not apply user-session `requireAuth()` to webhook routes.

## Diagnostics

When a backend endpoint fails auth:

1. Inspect whether the request contains `Authorization: Bearer <token>` or valid cookies.
2. Confirm CORS allows the origin and `Authorization` header.
3. Confirm proxies preserve authorization and forwarding headers.
4. Confirm backend middleware/plugin/filter runs before route handlers.
5. Confirm token type is accepted for the endpoint.
6. Confirm frontend and backend use the same Clerk instance/environment.
7. Confirm issuer/audience/JWKS settings match the instance when using manual verification.
8. Test with curl or an HTTP client, not only the browser UI.
9. Log auth diagnostics without logging tokens, secrets, session IDs, or signatures.

## Validation Checklist

- Middleware/plugin/filter registered before protected routes.
- Every mutating endpoint authenticates before parsing side-effect inputs.
- Authorization checks use server-derived user/org/session data.
- Cross-origin requests send awaited Bearer tokens.
- CORS allows only expected origins and required headers.
- Proxies preserve `Authorization` and forwarding headers.
- Secret keys and Backend API calls remain server-only.
- Language-specific JWT/manual verification checks signature, issuer, audience, expiration, token type, and key rotation behavior.
- Webhook routes verify Svix signatures and remain idempotent.

[View on SkillFed](https://skillfed.io/JosiahSiegel/claude-plugin-marketplace/clerk-backend-apis) · [View on GitHub](https://github.com/JosiahSiegel/claude-plugin-marketplace)