Authentication

Authenticate users and manage auth sessions

The Authentication API allows you to authenticate users via multiple methods including password, OAuth2, and one-time passwords (OTP).

Get auth methods

Retrieve available authentication methods for a collection.

GET /api/collections/{collection}/auth-methods

collection · string · required

The name or ID of the auth collection

Response

password · object

Password authentication configuration

Show child attributes

enabled · boolean

Whether password authentication is enabled

identityFields · array

Fields that can be used as identity (e.g., ["email", "username"])

oauth2 · object

OAuth2 authentication configuration

Show child attributes

enabled · boolean

Whether OAuth2 is enabled

providers · array

Available OAuth2 providers with auth URLs and PKCE parameters

otp · object

One-time password configuration

Show child attributes

enabled · boolean

Whether OTP authentication is enabled

duration · number

OTP validity duration in seconds

mfa · object

Multi-factor authentication configuration

Show child attributes

enabled · boolean

Whether MFA is enabled

duration · number

MFA session duration in seconds

curl

curl http://127.0.0.1:8090/api/collections/users/auth-methods

Authenticate with password

Authenticate a user with identity and password.

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

collection · string · required

The name or ID of the auth collection

Request body

identity · string · required

The user’s identity (email, username, or other configured field)

password · string · required

The user’s password

identityField · string

Specific field to use for identity lookup (leave empty for auto-detection)

Response

token · string

JWT authentication token

record · object

The authenticated user record

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "[e-mail]",
    "password": "your_password"
  }'

Authenticate with OAuth2

Authenticate a user via OAuth2 provider.

POST /api/collections/{collection}/auth-with-oauth2

collection · string · required

The name or ID of the auth collection

Request body

provider · string · required

OAuth2 provider name (e.g., google, github, facebook)

code · string · required

Authorization code from the OAuth2 provider

redirectURL · string · required

The redirect URL used in the initial OAuth2 request

codeVerifier · string

PKCE code verifier (required if provider uses PKCE)

createData · object

Additional data for creating a new user if one doesn’t exist

Response

token · string

JWT authentication token

record · object

The authenticated user record

meta · object

OAuth2 user data and isNew flag

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-oauth2 \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "code": "authorization_code",
    "redirectURL": "http://localhost:3000/auth/callback",
    "codeVerifier": "pkce_verifier"
  }'

Authenticate with OTP

Authenticate using a one-time password.

POST /api/collections/{collection}/auth-with-otp

collection · string · required

The name or ID of the auth collection

Request body

otpId · string · required

The OTP record ID

password · string · required

The OTP password/code

Response

token · string

JWT authentication token

record · object

The authenticated user record

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-otp \
  -H "Content-Type: application/json" \
  -d '{
    "otpId": "otp_record_id",
    "password": "123456"
  }'

Request OTP

Request a new one-time password to be sent to the user.

POST /api/collections/{collection}/request-otp

collection · string · required

The name or ID of the auth collection

Request body

email · string · required

The user’s email address

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/request-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Refresh authentication

Refresh an existing auth token.

POST /api/collections/{collection}/auth-refresh

collection · string · required

The name or ID of the auth collection

Authentication required: Yes (must be authenticated with the same collection)

Response

token · string

New JWT authentication token

record · object

The authenticated user record

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/auth-refresh \
  -H "Authorization: Bearer YOUR_TOKEN"

Request password reset

Request a password reset email.

POST /api/collections/{collection}/request-password-reset

collection · string · required

The name or ID of the auth collection

Request body

email · string · required

The user’s email address

Response

Returns 204 No Content on success (even if email doesn’t exist, to prevent enumeration).

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/request-password-reset \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Confirm password reset

Confirm password reset with token.

POST /api/collections/{collection}/confirm-password-reset

collection · string · required

The name or ID of the auth collection

Request body

token · string · required

The password reset token from the email

password · string · required

The new password

passwordConfirm · string · required

Password confirmation (must match password)

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-password-reset \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "new_password",
    "passwordConfirm": "new_password"
  }'

Request verification

Request an email verification message.

POST /api/collections/{collection}/request-verification

collection · string · required

The name or ID of the auth collection

Request body

email · string · required

The user’s email address to verify

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/request-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Confirm verification

Confirm email verification.

POST /api/collections/{collection}/confirm-verification

collection · string · required

The name or ID of the auth collection

Request body

token · string · required

The verification token from the email

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-verification \
  -H "Content-Type: application/json" \
  -d '{"token": "verification_token_from_email"}'

Request email change

Request to change the authenticated user’s email.

POST /api/collections/{collection}/request-email-change

collection · string · required

The name or ID of the auth collection

Authentication required: Yes

Request body

newEmail · string · required

The new email address

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/request-email-change \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newEmail": "[e-mail]"}'

Confirm email change

Confirm email change with token.

POST /api/collections/{collection}/confirm-email-change

collection · string · required

The name or ID of the auth collection

Request body

token · string · required

The email change token

password · string · required

The user’s current password

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-email-change \
  -H "Content-Type: application/json" \
  -d '{
    "token": "email_change_token",
    "password": "current_password"
  }'

Common error codes

Code	Description
400	Invalid credentials or validation error
403	Authentication method not enabled for collection
404	Collection not found or not an auth collection
429	Too many authentication attempts