Skip to main content

​
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 verifies your identity with a JSON Web Token (JWT). You obtain the token by signing up and then logging in. The token is valid for 7 days and must be included in the Authorization header of every subsequent request. This page covers all authentication endpoints and shows you exactly what each one returns.
Login and OAuth auth endpoints are rate-limited to 20 requests per 15-minute window per IP. Public signup has stricter burst and daily rate limits, plus optional Turnstile or reCAPTCHA verification when configured.

​
Sign up

Create a new user account. 
POST /auth/signup

​
Request body

​
email
string
required
A valid email address, maximum 255 characters.
​
password
string
required
Password, minimum 8 characters and maximum 128 characters.
​
botProtectionToken
string
Optional challenge token. Required only when SIGNUP_BOT_PROTECTION_PROVIDER is set to turnstile or recaptcha.

​
Response

​
id
string
The new user’s UUID.
​
email
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

StatusCondition
400Missing or invalid email/password
403Bot protection token is missing or invalid
409Account already exists for this email
429Signup burst or daily rate limit was exceeded

​
Log in

Exchange email and password for a JWT. 
POST /auth/login

​
Request body

​
email
string
required
Your registered email address.
​
password
string
required
Your password.

​
Response

​
token
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

StatusCondition
400Email or password missing
401Invalid credentials, or account uses OAuth login
429Rate 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

​
id
string
User UUID.
​
email
string
Email address.
​
name
string
Display name, may be null if not set.
​
role
string
Account role. Typically user or admin.
​
provider
string
OAuth provider (github, google, etc.) or null for password accounts.
​
avatar
string
Base64-encoded data:image/... avatar, or null.
​
created_at
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

​
name
string
Display name, 1–100 characters.
​
avatar
string
Base64-encoded image (data:image/png;base64,...), maximum 500 KB. Pass null to remove the avatar.

​
Response

​
name
string
Updated display name.
​
avatar
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

​
currentPassword
string
required
Your existing password.
​
newPassword
string
required
New password, minimum 8 characters and maximum 128 characters.

​
Response

​
success
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

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