Authentication
How a request proves who is signed in, and what the API answers when it can't.
Endpoints marked signed in in the API reference need a Clerk session. Public endpoints need nothing. Provider webhooks prove themselves with the provider's signature instead of a session.
From a browser on this site
Nothing to do. Signing in sets the __session cookie on this domain, and the browser sends it with every request to the API.
With a session token
Send the session token in the Authorization header:
GET /api/me HTTP/1.1
Authorization: Bearer <session token>
A Clerk frontend SDK running on this site gives you the token with getToken(). Tokens are short-lived, so ask for a fresh one before each request rather than storing it. The API accepts only tokens issued for its own origin: a token minted for another site is refused like a missing one.
Who you are
GET /api/me answers with your Clerk user id and the subject that owns your data and pays: your user in personal accounts, or your active Organization in team accounts.
When it fails
| Status | error |
Meaning |
|---|---|---|
401 |
sign_in_required |
No session, or it expired or was issued for another site. Sign in again or get a fresh token. |
403 |
organization_required |
Team accounts only: you're signed in, but no Organization is active. Choose one, then retry. |
503 |
auth_not_configured |
Sign-in isn't set up on this deployment. Retrying won't help; contact support. |
Every failure body has the same shape: { "error": "<code>" }.