clerk-backend-apis

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:

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 })
})