RimbraDocsDashboard

Rimbra Auth

Sign-up and sign-in for your apps: passwords, email links with codes, Google and GitHub, with tokens any backend can check.

Create an auth project

  1. Open Hosting → Auth in the dashboard and choose New auth project.
  2. Enter your app's name (people see it in sign-in emails) and its site URL (where email links send people back to).
  3. Copy the secret key shown once. It is only for your servers and the admin API; the browser never needs it.
  4. Copy the project URL from the Overview tab. It looks like https://api.rimbra.app/auth/v1/auth_…

Sign people in from the browser

Import the client from the project URL's host. It keeps the session in localStorage, renews the access token before it expires, and finishes any email link or Google/GitHub sign-in when the page opens with ?code= in the address.

js
import { createAuth } from "https://api.rimbra.app/auth/v1/client.js";

const auth = createAuth("https://api.rimbra.app/auth/v1/auth_YOUR_PROJECT");

// Email and password
await auth.signUp({ email, password, name });
await auth.signIn({ email, password });

// Email link + 6-digit code, no password
await auth.sendLink({ email });
await auth.verifyCode({ email, code: "123456" });

// Google or GitHub (turn them on under Sign-in methods first)
auth.signInWith("google");

// Who is signed in, and the token for your own API
await auth.ready;
const user = await auth.getUser();
const token = await auth.getToken();

auth.onChange((event, session) => console.log(event, session?.user));
await auth.signOut();

Check tokens on your server

Use app_data, which only your server can set, for roles and permissions; data can be changed by the user. Signing out, suspending a user or changing a password ends their sessions at Rimbra at once; tokens your own server already accepted stay valid until they expire (1 hour by default, set shorter in Settings).

Send the access token to your API as Authorization: Bearer. Access tokens are ES256 JWTs. Check them against the project's JWKS with any JWT library; the subject (sub) is the user's ID. No call to Rimbra is needed per request.

js
import { createRemoteJWKSet, jwtVerify } from "jose";

const PROJECT = "https://api.rimbra.app/auth/v1/auth_YOUR_PROJECT";
const jwks = createRemoteJWKSet(new URL(PROJECT + "/.well-known/jwks.json"));

export async function currentUser(req) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return null;
  const { payload } = await jwtVerify(token, jwks, { issuer: PROJECT, audience: "auth_YOUR_PROJECT" });
  return { id: payload.sub, email: payload.email, name: payload.name };
}

What a token carries

ClaimValue
subThe user's ID (a UUID). Use it as the key in your own tables.
email, email_verifiedThe address and whether it has been confirmed.
name, pictureWhen the user has them, from sign-up or Google/GitHub.
app_dataFields only your server sets (admin API appData), like a role or plan. Use these for permissions. Up to 4 KB of JSON.
dataFields the user can change themselves with updateUser({ data }). Never use them for permissions.
iss, audThe project URL and the project ID. Check both.
sid, expThe session, and when this token expires (1 hour by default).

Email links and redirects

Email links, password resets and Google/GitHub sign-in end on a page in your app with ?code=… added. The browser client swaps it for a session on its own; a server can do the same with POST /token?grant_type=code.

By default that page is the one that started the flow. It must be on your site URL's domain, on a URL listed under Settings → Other redirect URLs (end with * to allow every path), or on localhost.

After a password reset link, the client fires PASSWORD_RECOVERY: show a form and call auth.updateUser({ password }).

Google and GitHub

  1. Open your auth project → Sign-in methods and copy the callback URL.
  2. Google: in Google Cloud → APIs & Services → Credentials, create an OAuth client ID of type Web application and add the callback URL under Authorized redirect URIs.
  3. GitHub: in Settings → Developer settings → OAuth Apps, create an app and paste the callback URL as the Authorization callback URL.
  4. Paste the client ID and secret into Rimbra, save, and turn the provider on.

Send from your own domain

  1. Add and verify your domain in Emails → Domains, the same way you would for the Email API.
  2. Open your auth project → Settings → Emails and enter any address at that domain, like auth@example.com.
  3. Sign-in, confirmation and reset emails now come from that address under your app's name, signed with your domain's DKIM key, with no Rimbra mention.
  4. Turn on Email links and codes, and Confirm email, under Sign-in methods if your app uses them. New projects start with them off.

Manage users from your server

Use the secret key as Authorization: Bearer on the admin endpoints. Never send it to a browser.

bash
P=https://api.rimbra.app/auth/v1/auth_YOUR_PROJECT

# List or search users
curl "$P/admin/users?q=ada&page=1" -H "Authorization: Bearer $RIMBRA_AUTH_SECRET"

# Create a user with a confirmed email
curl -X POST "$P/admin/users" -H "Authorization: Bearer $RIMBRA_AUTH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"a long password","emailConfirm":true}'

# Suspend a user (signs them out everywhere)
curl -X PATCH "$P/admin/users/USER_ID" -H "Authorization: Bearer $RIMBRA_AUTH_SECRET" \
  -H "Content-Type: application/json" -d '{"banned":true}'

Endpoints

All paths start with the project URL. Errors come back as {"error": "…", "code": "…"}.

RequestWhat it does
POST /signup{ email, password, name?, data?, redirectTo? }. Returns a session, or confirmationSent when email confirmation is on: the account is created, with that password, when the link is used. To send the link again, call signup again.
POST /token?grant_type=password{ email, password } → session.
POST /token?grant_type=refresh_token{ refreshToken } → a new session. The old refresh token stops working.
POST /token?grant_type=code{ code, codeVerifier? } from a redirect → session.
POST /otp{ email, redirectTo? } emails a sign-in link and a 6-digit code. A new address gets its account when the link or code is used.
POST /verify{ email, code } → session. Only the newest code works, and an address gets five guesses an hour in all.
POST /recover{ email, redirectTo? } emails a password reset link.
POST /resend{ email } sends the confirmation email again.
GET /user, PUT /userThe signed-in user; change name, avatarUrl, data, password or email (a new email is confirmed by link).
POST /logout{ scope: "local" | "global" } ends this session or every session.
GET /authorize?provider=google|github&codeChallenge=…Starts Google or GitHub sign-in. A PKCE code challenge is required (the browser client adds it); send the matching codeVerifier with grant_type=code.
GET /.well-known/jwks.jsonThe public key for checking access tokens.
/admin/users…GET, POST, PATCH, DELETE with the secret key.

Plans and limits

  • Users are counted across all your auth projects.
  • Each address gets at most 6 sign-in emails an hour, and sign-in attempts are rate limited per IP address.
  • Emails come from your own address with your app's name as the sender name (see Send from your own domain).
PlanAuth projectsUsersSign-in emails an hour
Free210,00060
Launch550,000200
Pro20100,0001,000
Scale100500,0005,000