Authentication

How Praxiom AI authenticates users via Clerk and secures API requests with JWTs.

Overview

Praxiom AI uses Clerk for authentication. Every API request must include a valid JWT bearer token issued by Clerk. The backend verifies the token, resolves the user, and enforces workspace-level access control on every endpoint.

How It Works

Sign up or sign in

Users authenticate through the Clerk-powered sign-in flow on the frontend at praxiomai.xyz. Clerk supports email/password, Google OAuth, and other social providers.

When a new user signs up, Clerk fires a user.created webhook to POST /api/webhooks/clerk. The backend creates a local user record with an initial access_status of pending (when product-led growth gating is enabled) or active.

Obtain a JWT

After sign-in, Clerk issues a short-lived JWT. The frontend includes this token in every API request as a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Backend verification

The backend middleware extracts the JWT, verifies its signature against Clerk's public keys, and resolves the corresponding local user record. If the token is expired or invalid, the request is rejected with a 401 Unauthorized response.

Access control

Once authenticated, every workspace-scoped endpoint verifies that the user is a member of the requested workspace. If the user is not a member, the API returns 403 Forbidden with code FORBIDDEN.

Key Concepts

User Profile

Call GET /api/auth/me to retrieve the current user's profile. The response includes:

Field	Description
`id`	Internal user UUID
`email`	Primary email from Clerk
`name`	Full name
`clerkUserId`	Clerk's external user ID
`accessStatus`	One of `pending`, `active`, `suspended`
`hasProductAccess`	Whether the user can create workspaces and use the product
`isFounder`	Whether the user has permanent founder-level access
`referralCode`	The user's unique referral code
`activatedAt`	When the user gained product access (if applicable)

Access Status

Users go through a gated onboarding flow:

pending — Signed up but has not redeemed an access code. Cannot create workspaces.
active — Access code redeemed or PLG gate disabled. Full product access.
suspended — Access revoked by an admin.

The hasProductAccess boolean is the simplest check. It returns true when the user is active or has founder status.

Workspace Membership

Every workspace-scoped API call requires the authenticated user to be a WorkspaceMember of the target workspace. Membership roles include:

owner — Created the workspace. Can delete it and manage all settings.
admin — Can update workspace settings and manage members.
member — Can read and write workspace data (sources, insights, recommendations, documents).

Webhook Events

Clerk sends the following webhook events to POST /api/webhooks/clerk:

user.created — Creates a local user record
user.updated — Syncs email and name changes
user.deleted — Deletes the user and cascades to all owned data

The webhook endpoint uses Svix signature verification, not JWT auth. Never expose your Clerk webhook signing secret.

API Authentication Example

curl -H "Authorization: Bearer YOUR_CLERK_JWT" \
     https://api.praxiomai.xyz/api/auth/me

A successful response returns your user profile JSON. If the token is missing or invalid, you receive:

{"detail": "Not authenticated"}

What's Next

Now that you understand authentication, dive into the core workflows starting with Research Upload.

Was this helpful?

PreviousSkills NextRecommendations