Authenticate with the Nora API

Sign up, log in, and manage your Nora account via the Auth API. Includes JWT token usage, profile updates, and password management.

Every protected Nora API endpoint requires an authenticated identity — either a session JWT (covered on this page) or a workspace API key with scopes (see the API overview for the key-and-scope model). When the operator allows registration, a new user can sign up and then log in to obtain a JWT. Existing users can continue to log in when registration is disabled. A JWT is valid for 7 days, sent as a Bearer token in the Authorization header of every subsequent request, and also accepted as an HttpOnly session cookie. This page covers all authentication endpoints and shows you exactly what each one returns.

An explicit Authorization, X-Api-Key, or X-Nora-Api-Key credential takes precedence over the ambient nora_auth cookie. Do not send conflicting explicit credentials: Nora rejects them with 400 conflicting_auth before either token is verified.

Login and OAuth auth endpoints are rate-limited to 20 requests per 15-minute window per IP. When enabled, public signup has stricter burst and daily rate limits, plus Turnstile or reCAPTCHA verification when configured. Hosted PaaS mode requires one of those providers and fails closed when neither is configured; self-hosted mode may explicitly use none.

Bootstrap status

Check whether a self-hosted server still needs its first admin. This drives the “claim this server” first-run flow: until the first user registers (that first account becomes the platform admin), needsFirstAdmin is true; afterward it is false. It is also false whenever public signup is disabled. Hosted PaaS requires an explicit bootstrap administrator before startup and never reports public first-admin claim. The response also contains runtime OAuth visibility, signup availability, normalized platform mode, and signup-challenge metadata so published frontend images can render the correct auth surface without build-time replacement. Verification secrets are never returned. A user count or emails would aid account enumeration. See the security overview for the broader claim flow.

GET /auth/bootstrap-status

Public — no authentication required.

Response

boolean

true only while an empty self-hosted installation permits first-account admin claim. Hosted PaaS always reports false.

Whether the running backend accepts OAuth login. Login and signup hide OAuth controls unless this value is true.

string

Normalized deployment mode: selfhosted or paas.

Whether the operator currently allows new password or OAuth registrations. Existing-account login remains available when this is false.

Safe public runtime configuration: enabled, provider, public siteKey, configured, and a user-safe configurationError. Secret verification keys remain backend-only.

curl http://localhost:8080/api/auth/bootstrap-status

{
  "needsFirstAdmin": true,
  "oauthLoginEnabled": false,
  "platformMode": "selfhosted",
  "signupEnabled": true,
  "signupBotProtection": {
    "enabled": true,
    "provider": "turnstile",
    "siteKey": "0x4AAAA...",
    "configured": true,
    "configurationError": null
  }
}

Create a new user account when the operator has enabled public registration. On an empty self-hosted installation, the first registered user becomes the platform admin (the first-admin claim flow — see bootstrap status and the security overview). Hosted PaaS must seed its administrator before startup, so public signup there always creates a regular user. Operators can disable new password and OAuth registrations with SIGNUP_ENABLED=false; password login and sessions for existing users are unaffected.

POST /auth/signup

Request body

string

required

A valid email address, maximum 255 characters.

string

required

Password, minimum 8 characters and maximum 128 characters.

string

Optional challenge token. Required only when SIGNUP_BOT_PROTECTION_PROVIDER is set to turnstile or recaptcha.

Response

string

The new user’s UUID.

string

The registered email address.

curl -X POST http://localhost:8080/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"securepassword"}'

{
  "id": "d4e5f6a7-b8c9-4d01-a234-56789bcdef01",
  "email": "you@example.com"
}

Error responses

When registration is disabled, the response has a stable machine-readable code:

{
  "error": "Registration is disabled by this Nora operator.",
  "code": "SIGNUP_DISABLED"
}

Status	Condition
`400`	Missing or invalid email/password
`403`	Registration is disabled (`code: "SIGNUP_DISABLED"`)
`403`	Bot protection token is missing or invalid
`409`	Account already exists for this email
`429`	Signup burst or daily rate limit was exceeded

Log in

Exchange email and password for a JWT.

POST /auth/login

Request body

string

required

Your registered email address.

string

required

Your password.

Response

string

A signed JWT valid for 7 days. Include this value in the Authorization: Bearer <token> header on all subsequent requests.

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"securepassword"}'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error responses

Status	Condition
`400`	Email or password missing
`401`	Invalid credentials, or account uses OAuth login
`429`	Rate limit exceeded

Using the token

Pass the token you received from /auth/login in every request to a protected endpoint:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens expire after 7 days. Your client should catch 401 responses and redirect the user to log in again.

Get current user

Verify a token and retrieve the authenticated user’s profile.

GET /auth/me

Requires authentication.

Response

string

User UUID.

string

Email address.

string

Display name, may be null if not set.

string

Account role. Typically user or admin.

string

OAuth provider (github, google, etc.) or null for password accounts.

string

Base64-encoded data:image/... avatar, or null.

string

ISO 8601 timestamp of account creation.

TOKEN="paste-your-token-here"
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/auth/me

{
  "id": "d4e5f6a7-b8c9-4d01-a234-56789bcdef01",
  "email": "you@example.com",
  "name": "Alex Smith",
  "role": "user",
  "provider": null,
  "avatar": null,
  "created_at": "2025-01-15T10:30:00.000Z"
}

Update profile

Update your display name and/or avatar.

PATCH /auth/profile

Requires authentication.

Request body

string

Display name, 1–100 characters.

string

Base64-encoded image (data:image/png;base64,...), maximum 500 KB. Pass null to remove the avatar.

Response

string

Updated display name.

string

Updated avatar value or null.

curl -X PATCH http://localhost:8080/api/auth/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex Smith"}'

{
  "name": "Alex Smith",
  "avatar": null
}

Change password

Replace your current password with a new one.

PATCH /auth/password

Requires authentication. Not available for OAuth-only accounts.

Request body

string

required

Your existing password.

string

required

New password, minimum 8 characters and maximum 128 characters.

Response

boolean

true when the password was updated successfully.

curl -X PATCH http://localhost:8080/api/auth/password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"oldpass","newPassword":"newpass123"}'

{ "success": true }

Error responses

Status	Condition
`400`	Missing fields, or account has no password (OAuth account)
`401`	Current password is incorrect
`404`	User record not found

Exchange a server-verified OAuth identity for a Nora session. On success this returns a token plus the user record and sets the HttpOnly session cookie.

POST /auth/oauth-login

This endpoint is disabled by default. Unless OAUTH_LOGIN_ENABLED=true, it returns 403. Google or GitHub credentials must also be configured in the marketing OAuth bridge. Provider tokens are verified server-side before Nora issues a session. Like password login, this endpoint is rate-limited to 20 requests per 15-minute window per IP. When OAuth is enabled but public signup is disabled, an existing linked OAuth user can still authenticate. A verified identity that would create a new Nora user receives 403 with code: "SIGNUP_DISABLED".

Request body

string

required

OAuth provider identifier (for example github or google).

string

Provider access token. Either this or oauthIdToken is required.

string

Provider ID token. Either this or oauthAccessToken is required.

Response

string

A signed JWT for the linked or newly created account.

object

The authenticated user record.

Upgrade session

Mirror an existing Bearer-token session into the browser’s HttpOnly session cookie. The supplied token is re-verified, so a forged Bearer is rejected.

POST /auth/session-upgrade

Requires authentication. Send the token in the Authorization: Bearer <token> header.

Response

boolean

true when the cookie was set.

{ "success": true }

Log out

Clear the session cookie.

POST /auth/logout

This endpoint intentionally requires no authentication, so a page holding a stale or invalid cookie can still clean itself up.

Response

boolean

true when the cookie was cleared.

{ "success": true }

Getting started

Concepts

Configuration

Guides

API Reference

Support

Authentication

Authenticate with the Nora API

Bootstrap status

Response

Request body

Response

Error responses

Log in

Request body

Response

Error responses

Using the token

Get current user

Response

Update profile

Request body

Response

Change password

Request body

Response

Error responses

Request body

Response

Upgrade session

Response

Log out

Response

​Authenticate with the Nora API

​Bootstrap status

​Response

​Sign up

​Request body

​Response

​Error responses

​Log in

​Request body

​Response

​Error responses

​Using the token

​Get current user

​Response

​Update profile

​Request body

​Response

​Change password

​Request body

​Response

​Error responses

​OAuth login

​Request body

​Response

​Upgrade session

​Response

​Log out

​Response

Authenticate with the Nora API

Bootstrap status

Response

Sign up

Request body

Response

Error responses

Log in

Request body

Response

Error responses

Using the token

Get current user

Response

Update profile

Request body

Response

Change password

Request body

Response

Error responses

OAuth login

Request body

Response

Upgrade session

Response

Log out

Response