Authentication API

The Authentication API provides endpoints for user authentication, token management, and password operations.

Base Endpoint


/api/auth

BSH Engine Collection

Endpoints

Method	Endpoint	Description
POST	`/api/auth/register`	Register new user
POST	`/api/auth/activate-account`	Activate user account using verification code
POST	`/api/auth/login`	Authenticate user with email and password
POST	`/api/auth/refresh`	Refresh expired access token
POST	`/api/auth/forget-password`	Request password reset code via email
POST	`/api/auth/reset-password`	Reset password using verification code
POST	`/api/auth/resend-activation-email`	Resend activation email to the user

Token usage

Choose one primary style per client. You can mix API keys and JWT in different apps, but a single request should use one method.

JWT (Bearer)

Send the access token on each request:


Authorization: Bearer {{accessToken}}

Silent refresh (header clients): also send the refresh token so the engine can renew an expired access token without a separate refresh call:


X-BSH-REFRESHTOKEN: {{refreshToken}}

When refresh happens during the request, the JSON body may include the new access token at meta.accessToken. See Refresh Token.

If both Authorization: Bearer … and cookie session cookies are present, header auth takes precedence for that request.

Cookies

After login, the engine sets bsh_access_token and bsh_refresh_token cookies. Browsers can call protected routes with cookies and no Authorization header.

CSRF: For mutating requests (POST, PUT, DELETE, …) using cookie sessions, include the CSRF token:


X-XSRF-TOKEN: {{value from XSRF-TOKEN cookie}}

CSRF is not required when authenticating with Authorization (JWT Bearer or API key).

The default SDK fetch client sends credentials: 'include' and attaches X-XSRF-TOKEN for mutating calls when no JWT/API key auth is configured.

API key

Send the API key as the raw Authorization value (not Bearer):


Authorization: {{ApiKey}}

See Using your API key.

Previous releases (before 0.0.6): API keys used the X-BSH-APIKEY header. That header is deprecated—use Authorization with the raw key instead.

If a JWT session is already established, API key authentication on the same request does not override it.