Auth
Excalibase Auth issues and verifies JWTs for a project's end users, and exchanges a publishable key for the token an app uses before anyone signs in. These are your app's users, not the people who log in to Studio.
On Excalibase Cloud
Every route is project-scoped and lives under the same host as the API:
https://api.excalibase.io/auth/{orgSlug}/{projectId}/...
{orgSlug} is a label that auth ignores; Studio, the SDK and these docs write the project id twice
(/auth/proj-xxxxxxxxxx/proj-xxxxxxxxxx/token). Tokens are signed with ES256 and carry an audience
bound to the project, so a token minted for one project is rejected by another. Set BASE,
PROJECT_ID, KEY and TOKEN as in Connect to your project.
Anonymous: exchange a publishable key
curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/token" \
-H "Content-Type: application/json" \
-d "{\"grant_type\":\"api_key\",\"api_key\":\"$KEY\"}"
The token's role is anon. Sending no token at all runs as anon too, so the exchange is for the SDK
and for clients that want a verified identity on every call.
Sign up and sign in
An end user registers with an email, a password and a name, then signs in through the unified
/token endpoint (grant_type password) or /login:
curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/register" \
-H "Content-Type: application/json" \
-d '{"email":"alice@example.com","password":"a-long-password","fullName":"Alice"}'
curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/token" \
-H "Content-Type: application/json" \
-d '{"grant_type":"password","email":"nobody@example.com","password":"wrong-password-1"}'
The second call answers 401 {"error":"invalid email or password"}: a wrong password and an unknown
email look the same. A success returns accessToken, refreshToken, expiresIn and the user.
The user's token has the role user, and its userId feeds the
permissions that scope rows to their owner. userId is the user's database
id as a JSON number ("userId": 42). There is no email claim: the token's sub is the user's
email, which permissions read as X-Excalibase-Email.
Check a token
curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/validate" \
-H "Content-Type: application/json" \
-d "{\"token\":\"$TOKEN\"}"
{ "email": "apikey:1", "projectId": "proj-jfp7kx46kb", "role": "anon", "valid": true }
Endpoints
| Route | Purpose |
|---|---|
POST /register | Create a user. Sends a verification email when the project requires it. |
POST /login | Exchange email and password for an access and refresh token. |
POST /token | OAuth2-shaped unified endpoint, dispatching on grant_type. |
POST /refresh | Legacy alias for grant_type=refresh_token. |
POST /validate | Verify a token and return its claims. |
POST /logout | Revoke the session. |
GET / POST /verify-email | Redeem a verification link, or post the token directly. |
POST /resend-verification | Re-send the verification email, rate limited per address. |
POST /forgot-password | Start a reset. Single-use, hashed token. |
POST /reset-password | Complete a reset and revoke existing sessions. |
/api-keys | Create, list and revoke project API keys. Requires a JWT. |
Rate limiting
Register, login and token are throttled per IP, per identity and per project, with a separate budget for repeated login failures.
How it relates to permissions
Auth issues the token; the engine enforces access. Claims from the token feed
the permission layer: a filter such as owner_id = X-Excalibase-User-Id shows
only the caller's rows, on GraphQL, REST and realtime. See
Permissions.
Not yet available
- Social sign-in with Google, GitHub or Discord. The OAuth2-shaped
/tokenendpoint implements the grant-type flow, not third-party providers.
Self-hosting
Auth runs beside the engine in the all-in-one deployment and is exercised by the end-to-end suite
on every release. On your own stack the routes and bodies are the same; only the host changes, for
example http://localhost:24000/auth/{orgSlug}/{projectId}/token. Rate limits are configurable
through environment variables.