Auth

Sign in to an auth collection and manage sessions. To sign up, create a record in the auth collection.

Sign in with a password

Checks the password and the collection's authRule, then starts a session. Every failure returns the same error, so responses never reveal which emails exist. Ten failures for one account within 15 minutes block it for the rest of that window.

SDK

// Bearer token, kept by the SDK's auth store:
await nb.collection("users").signInWithPassword("ann@example.com", "a long password");

// Or an HttpOnly session cookie:
await nb.collection("users").signInWithPassword("ann@example.com", "a long password", {
  cookie: true,
});

curl

curl -X POST https://app.example/api/nextbase/collections/users/auth-with-password \
  -H 'content-type: application/json' \
  -d '{"identity":"ann@example.com","password":"a long password"}'

POST /collections/{collection}/auth-with-password

Body

Param	Type	Description
identity	string	Required. The email (matched regardless of case), or another identity field.
password	string	Required.
cookie	boolean	Optional. true sets the session cookie instead of returning the token. The request must then send an Origin header naming this site.

Query parameters: expand and fields, applied to record.

Responses

200

{
  "token": "yK2v0Xo8...43 characters",
  "record": {
    "collectionId": "c9d8e7f6a5b4c3d",
    "collectionName": "users",
    "id": "u7v8w9x0y1z2a3b",
    "email": "ann@example.com",
    "emailVisibility": false,
    "verified": false,
    "name": "Ann"
  }
}

With cookie: true, token is left out and the response sets:

Set-Cookie: nextbase_session=<token>; Path=/; Max-Age=604800; HttpOnly; SameSite=Lax; Secure

400

{ "status": 400, "message": "Failed to authenticate.", "data": {} }

403

{ "status": 403, "message": "This account does not meet the requirements to sign in.", "data": {} }

The password matched, but the authRule did not.

429

{ "status": 429, "message": "Too many failed attempts. Try again later.", "data": {} }

Refresh

Extends the current session to its full lifetime and returns the record, re-checking the authRule. A cookie session gets a renewed cookie and never the token.

SDK

await nb.collection("users").refreshSession();

curl

curl -X POST https://app.example/api/nextbase/collections/users/auth-refresh \
  -H 'authorization: Bearer <token>'

POST /collections/{collection}/auth-refresh

Responses

200

{ "token": "...", "record": { ... } }, without token for cookie sessions.

401

{ "status": 401, "message": "Sign in to this collection to refresh.", "data": {} }

Get the current session

Returns the caller's session and record, or null when signed out.

SDK

const session = await nb.getSession();

curl

curl https://app.example/api/nextbase/session -H 'authorization: Bearer <token>'

GET /session

Responses

200

{
  "id": "s1t2u3v4w5x6y7z",
  "created": "2026-10-19T09:30:00.000Z",
  "expires": "2026-10-26T09:30:00.000Z",
  "userAgent": "Mozilla/5.0 ...",
  "current": true,
  "record": { "collectionName": "users", "id": "u7v8w9x0y1z2a3b", "email": "ann@example.com" }
}

null when signed out.

Sign out

Ends the current session, so its token stops working, and removes the session cookie.

SDK

await nb.signOut();

curl

curl -X DELETE https://app.example/api/nextbase/session -H 'authorization: Bearer <token>'

DELETE /session

Responses: 204 with no body, also when there was no session.

List sessions

Lists the signed-in record's live sessions, newest first: one per device or client.

SDK

const sessions = await nb.listSessions();

curl

curl https://app.example/api/nextbase/sessions -H 'authorization: Bearer <token>'

GET /sessions

Responses

200

{
  "items": [
    {
      "id": "s1t2u3v4w5x6y7z",
      "created": "2026-10-19T09:30:00.000Z",
      "expires": "2026-10-26T09:30:00.000Z",
      "userAgent": "Mozilla/5.0 ...",
      "current": true
    }
  ]
}

401

{ "status": 401, "message": "Sign in to manage sessions.", "data": {} }

Revoke a session

Ends one of the signed-in record's sessions, such as a lost device. Revoking the current cookie session also removes the cookie.

SDK

await nb.revokeSession("s1t2u3v4w5x6y7z");

curl

curl -X DELETE https://app.example/api/nextbase/sessions/s1t2u3v4w5x6y7z \
  -H 'authorization: Bearer <token>'

DELETE /sessions/{id}

Responses

204

No body.

401

{ "status": 401, "message": "Sign in to manage sessions.", "data": {} }

404

{ "status": 404, "message": "Session not found.", "data": {} }

Also returned for another record's session.