Skip to content
excalibase
auth
Authbeta

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

RoutePurpose
POST /registerCreate a user. Sends a verification email when the project requires it.
POST /loginExchange email and password for an access and refresh token.
POST /tokenOAuth2-shaped unified endpoint, dispatching on grant_type.
POST /refreshLegacy alias for grant_type=refresh_token.
POST /validateVerify a token and return its claims.
POST /logoutRevoke the session.
GET / POST /verify-emailRedeem a verification link, or post the token directly.
POST /resend-verificationRe-send the verification email, rate limited per address.
POST /forgot-passwordStart a reset. Single-use, hashed token.
POST /reset-passwordComplete a reset and revoke existing sessions.
/api-keysCreate, 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 /token endpoint 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.