Skip to main content

​
How authentication works

ForgeAI uses Clerk for identity. The Elysia server mounts the elysia-clerk plugin on every route group, which validates the session before your handler runs. Browser requests are authenticated automatically via the Clerk session cookie set when you sign in to the ForgeAI web app. Programmatic requests can pass a Bearer token in the Authorization header: 
Authorization: Bearer <clerk_session_token>
Clerk session tokens are short-lived JWTs. Obtain one from your Clerk dashboard or via the Clerk frontend SDK (session.getToken()).

​
Unauthenticated requests

If no valid session is present, every endpoint returns: 
{
  "error": "Unauthorized"
}
with HTTP status 401.

​
Pro feature gates

Some endpoints (and some parameters on shared endpoints) are gated behind a Pro subscription. ForgeAI checks for the following Clerk feature flags:
Feature flagWhat it unlocks
screenshot_uploadAttach a design screenshot (imageUrl) when creating projects or sending messages
inline_code_editUpdate files directly in a live sandbox via PATCH /api/fragments/:fragmentId
When a Pro-gated action is attempted without the required feature flag, the API returns: 
{
  "error": "Pro is required"
}
with HTTP status 403.

​
Signing in

1

Create a ForgeAI account

Visit your ForgeAI instance and sign up or sign in using Clerk’s hosted authentication flow.
2

Use the web app normally

All API calls made from the browser use your session cookie automatically — no extra configuration needed.
3

Retrieve a session token for scripts

Use the Clerk frontend SDK to get a short-lived JWT for use in the Authorization header when calling the API from outside the browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us