🔓 Anonymous Authentication
Anonymous authentication allows a client application (e.g., a VR app) to obtain a valid JWT token pair without requiring the end user to register or log in. The backend automatically generates a unique identity, creates a new end user, and returns a long-lived token — enabling a seamless, frictionless first experience.
This feature is controlled by a feature flag that must be enabled per project by a user with Features Update permission. See Features for configuration details.
✨ How It Works
- A client application sends a request to the anonymous login endpoint.
- The backend verifies that anonymous authentication is enabled for the specified project.
- A new end user is created with a unique, auto-generated identity (e.g.
anonymous_1,anonymous_2, …). - A JWT token pair (access token + long-lived refresh token) is generated and returned.
- The client uses these tokens to authenticate subsequent requests to backend services.
🌐 API Endpoint
POST /domain/users/auth/login/anonymous/:projectId
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | ✅ Yes | The unique name/identifier of the project. |
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
x-tenant-id | string | ✅ Yes | Your Tenant ID. |
Request Body
None. This endpoint does not require a request body.
Responses
| Status | Description |
|---|---|
201 | Success — returns a JWT token pair (accessToken + refreshToken). |
400 | Bad Request — projectId parameter is missing or invalid. |
403 | Forbidden — anonymous authentication is disabled for this project. |
404 | Not Found — the specified project does not exist. |
Example Response
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
⚙️ Configuration
Anonymous authentication is disabled by default. To enable it, go to Features → Preferences → Authentication for the relevant project and configure the following settings:
| Setting | Default | Description |
|---|---|---|
| Anonymous authentication (toggle) | Off | Enables or disables the anonymous login endpoint for this project. |
| Anonymous authentication token expiration time | 1y | Sets the lifetime of the long-lived refresh token issued to anonymous users. Uses JWT duration format (see table below). |
Duration Format
Expiration values must follow the JWT duration format:
| Format | Example | Meaning |
|---|---|---|
m | 15m | 15 minutes |
h | 8h | 8 hours |
d | 30d | 30 days |
y | 1y | 1 year |
The access token uses the project's standard JWT expiration time. Only the refresh token lifetime is controlled by the anonymous authentication expiration setting.
🔐 Security Considerations
- Each anonymous user receives a unique, sequential identity (e.g.
anonymous_1) generated by the backend — there is no risk of identity collision. - The generated tokens grant access only to the specific project the request was made for.
- Because anonymous users are real end-user records in the database, they appear in the All Users list. You can identify them by their
anonymous_*identity prefix. - Anonymous users cannot be linked to a real identity after creation. If you need persistent user accounts, use a standard registration or invitation flow.
- Set the token expiration time to the shortest value appropriate for your use case to limit exposure of long-lived tokens.
💡 Business Case
Imagine a public VR demo kiosk where visitors put on a headset and immediately start an experience — no account creation, no login screen.
- The VR application calls the anonymous authentication endpoint on startup.
- A new anonymous end user is created instantly, and the app receives a valid JWT.
- The user's session data (metrics, progress) is recorded under their anonymous identity.
- If the user later creates a real account, the session history remains in the platform under the original anonymous profile.
Benefits
- Zero friction for end users — the experience starts immediately.
- All session data is still captured and available in the admin platform.
- Feature flag control means you can enable this only for projects that need it.