Authentication

Authentication Model

Praxiom AI uses Clerk for authentication. Every API request must include a valid Clerk JWT token in the Authorization header.

Authorization: Bearer <clerk_jwt_token>

Obtaining a Token

From the Frontend SDK

If you are building on top of the Praxiom frontend, the Clerk React SDK provides the token automatically:

import { useAuth } from "@clerk/nextjs";

const { getToken } = useAuth();
const token = await getToken();

const res = await fetch("https://api.praxiomai.xyz/api/workspaces", {
  headers: { Authorization: `Bearer ${token}` },
});

From the Clerk Backend SDK (Server-to-Server)

For backend integrations, use the Clerk Backend SDK to generate a session token:

from clerk_backend_api import Clerk

clerk = Clerk(bearer_auth="sk_live_...")
# Use a valid session ID to get a token
session = clerk.sessions.get(session_id="sess_...")
token = session.last_active_token

How It Works

1. The client sends a request with the Authorization: Bearer <token> header.
2. The backend verifies the JWT signature against Clerk's JWKS endpoint.
3. The backend extracts the user's clerk_id from the token claims.
4. The user record is looked up (or created on first request via the /webhooks/clerk webhook).
5. The authenticated user object is injected into the route handler.

User Object

After authentication, the API has access to the current user's profile:

Field	Type	Description
id	UUID	Internal user ID
clerk_id	string	Clerk user identifier
email	string	User's email address
name	string	Display name
has_product_access	boolean	Whether the user has redeemed an access code

Workspace Authorization

Most endpoints also require workspace membership. After authenticating the user, the API checks that the user is a member of the requested workspace via the workspace_members table. If not, a 403 FORBIDDEN error is returned.

Common Auth Errors

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid JWT token
403	FORBIDDEN	User is not a member of the requested workspace
403	ACCESS_REQUIRED	User has not redeemed an access code (for workspace creation)