Authentication

Sign-up and sign-in for your application users.

Every project includes CubiBase Auth. Your app calls /auth/v1/signup and /auth/v1/token on the project host with the publishable key. CubiBase stores the user in the project database, hashes the password with Argon2id, and returns an access JWT plus a rotating refresh token. That access token is the end-user JWT your Data API calls already need.

  1. Your app

    email + password

  2. CubiBase Auth

    Argon2id hash

  3. Your database

    example_project_db

Illustration. Sign-up returns the JWT your Data API calls use.

The flows your app calls

All auth endpoints live on the project host under /auth/v1 and require the apikey header, the same publishable key as the Data API. The user’s password travels in the request body over HTTPS and is never stored in plain text.

  • POST /auth/v1/signup creates a user and returns a session: user, accessToken, refreshToken, expiresIn.
  • POST /auth/v1/token?grant_type=password signs a user in with email and password.
  • POST /auth/v1/token?grant_type=refresh_token exchanges a refresh token for a new session.
  • POST /auth/v1/logout revokes the session behind a refresh token.
  • GET /auth/v1/user returns the signed-in user, read from the bearer token.

The access token is HS256, signed with the project’s signing secret. Its sub claim is the user id, and that id becomes cubibase.user_id for Data API transactions. A table with a user column now has a real person behind every row policy check.

Sign up · request
POST https://example-project.api.cubibase.com/auth/v1/signup
apikey: cb_pub_EXAMPLE_ONLY
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "<USER_PASSWORD>"
}
Sign up · 201 response (trimmed)
{
  "user": {
    "id": "3f2b8c1e-9a47-4d02-b6e5-1c8f0a3d7e29",
    "email": "[email protected]",
    "emailVerifiedAt": "2026-11-18T09:12:44.000Z",
    "providers": ["email"],
    "mfaEnabled": false
  },
  "accessToken": "<ACCESS_JWT>",
  "refreshToken": "<REFRESH_TOKEN>",
  "tokenType": "Bearer",
  "expiresIn": 3600
}
Sign in
POST https://example-project.api.cubibase.com/auth/v1/token?grant_type=password
apikey: cb_pub_EXAMPLE_ONLY
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "<USER_PASSWORD>"
}

Sessions that rotate and can be revoked

By default an access token lives for one hour and a refresh token for 30 days. Refreshing issues a new pair and retires the old refresh token. If a retired refresh token is presented again, CubiBase revokes the whole token family, so a stolen copy stops working.

Every Data API request checks that the session behind the token is still live. Revoking a session, or banning a user, takes effect on the next request, not when the access token expires.

Refresh the session
POST https://example-project.api.cubibase.com/auth/v1/token?grant_type=refresh_token
apikey: cb_pub_EXAMPLE_ONLY
Content-Type: application/json

{
  "refreshToken": "<REFRESH_TOKEN>"
}

Email and password return an access JWT and a refresh token.

accessToken · 1 h

Illustration with fictional tokens. It does not query CubiBase.

TOTP multi-factor, per project

Turn MFA on in the project’s auth settings and users can enroll an authenticator app: POST /auth/v1/factors returns a TOTP secret and URI, and POST /auth/v1/factors/verify confirms the first code. You can also make MFA required for the whole project.

When a user with a verified factor signs in, the password grant returns an MFA challenge instead of a session. The app posts the challenge id and the six-digit code to /auth/v1/token?grant_type=mfa and receives the session. Challenges expire after five minutes.

Settings you control per project

  • Signup and password sign-in can each be switched off.
  • Minimum password length defaults to 8 characters.
  • Access token TTL defaults to 1 hour; refresh token TTL defaults to 30 days.
  • MFA can be optional or required.
  • Rate limits per project: 30 signups per hour and 30 sign-ins per minute per IP by default, adjustable.

These settings and the user directory are managed through the control API today: users, sessions, factors, and auth events. Auth events are also mirrored into the project’s logs schema, readable from the Console SQL editor.

auth.usersexample-project
Fictional end users in the auth schema
emailverifiedmfalast sign-in
[email protected]yestotp2 minutes ago
[email protected]yes—1 hour ago
[email protected]no—Never
Illustration. Users live in your project database, not a shared directory.

What email verification does today

By default, signup marks the email as verified immediately (autoconfirm). CubiBase does not send a confirmation email to your end users yet. If you turn autoconfirm off, new users start unverified and you can mark them verified through the control API. Keep that in mind when you design your onboarding.

Already have an identity provider?

You can keep it. Configure the project with a JWKS URL, issuer, and audience, and CubiBase verifies RS256 tokens from that provider on every Data API request. CubiBase Auth and an external provider are alternatives; a project’s requests are checked against the provider configuration you set.

While building, a development token issuer can mint an HS256 token for a user id you choose, when that issuer is enabled. Social login buttons and SAML are not part of the current engine.

Questions

Where do my application users live?

In the auth schema of your project’s own PostgreSQL database, in auth.users. Passwords are stored only as Argon2id hashes. Refresh tokens are stored as hashes too.

Do I still need my own auth server?

Not for email and password. Signup, sign-in, refresh, logout, and TOTP MFA are served by the project host. You still build the screens in your app; CubiBase answers the HTTP calls.

Does CubiBase send verification emails to my users?

Not yet. Autoconfirm marks new users verified at signup by default. If you disable it, verification is managed through the control API. Developer-account emails from the Console are a separate flow.

What happens when a refresh token is stolen and reused?

Refresh tokens rotate. When a token that was already replaced is presented again, CubiBase revokes the entire token family and the attacker’s session dies with it.

Open the Console.

Create a project when you are ready to provision a database.

first request
GET /rest/v1/customersapikey: cb_pub_…Authorization: Bearer <JWT>200 · { "data": [ … ] }