User Registration and Authentication Guide

This guide provides step-by-step instructions for user self-registration, authentication, and token refresh in our system. It includes details on how to use the "Accept-Language" header for localized responses and the "X-Device-ID" header for device identification.

Step 1: Initiate Registration

1. Send a POST request to /v1/users/initiate-registration
2. Headers:

   Content-Type: application/json
   X-API-Key: your_api_key_here
   Accept-Language: en  // Use 'de', 'fr', or 'it' for other supported languages

3. Request Body:

   {
     "credential_type": "email",
     "credential_value": "jane.smith@example.com",
     "password": "securePassword123!",
     "terms_accepted": true,
     "privacy_policy_accepted": true
   }

4. Expected Response (200 OK):

   {
     "message": "We've sent a verification code to your email. Please check and enter the code to complete your registration.",
     "user_id": "12345678-1234-1234-1234-123456789012"
   }

Step 2: Validate Credential

1. Send a POST request to /v1/users/verify-registration
2. Headers:

   Content-Type: application/json
   X-API-Key: your_api_key_here
   Accept-Language: en  // Use 'de', 'fr', or 'it' for other supported languages

3. Request Body:

   {
     "user_id": "12345678-1234-1234-1234-123456789012",
     "credential_type": "email",
     "otp": "123456"
   }

4. Expected Response (200 OK):

   {
     "message": "Your account has been successfully verified and activated.",
     "status": "success"
   }

Step 3: Authenticate User

1. Send a POST request to /v1/authenticate
2. Headers:

   Content-Type: application/json
   X-Device-ID: device_id_here
   X-App-ID: web-app
   Accept-Language: en

3. Request Body:

   {
     "username": "jane.smith@example.com",
     "password": "securePassword123!"
   }

Response when mfa_mode is off

No interactive MFA step. The server issues a full session:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "idle_timeout_seconds": 900,
  "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc"
}

The refresh-token HTTP-only cookie is set in the same response.

Response when MFA is required (email, phone, or totp)

Password verification succeeds, but no authenticated session yet. The response is a pre-auth challenge:

{
  "credential_type": "email",
  "message": "OTP sent successfully",
  "challenge_token": "eyJ0eXAi...",
  "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc"
}

• challenge_token is pre-auth only. Do not send it as Authorization: Bearer on protected routes or on /v1/refresh-token.
• If TOTP must be enrolled first, credential_type may be totp_setup_required (complete TOTP setup before /v1/verify-2FA).
• Continue with Step 4 to obtain access_token and the refresh cookie.

Step 4: Verify 2FA (When MFA Is Required)

Complete login after Step 3 returned a challenge (not when Step 3 already returned access_token).

1. Send a POST request to /v1/verify-2FA
2. Headers:

   Content-Type: application/json
   X-Device-ID: device_id_here
   X-App-ID: web-app
   Accept-Language: en
   X-MFA-Challenge: eyJ0eXAi...   # challenge_token from Step 3; required when auth.2fa_challenge=true

3. Request Body:

   {
     "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc",
     "otp": "123456"
   }

4. Expected Response (200 OK):

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "expires_in": 900,
     "idle_timeout_seconds": 900,
     "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc"
   }

This is the only step that turns an MFA login into a full session (access_token + refresh cookie).

Do not confuse with credential enrollment. Adding a phone or email credential via /v1/users/credentials is account setup. Login MFA is driven by the user's mfa_mode and /v1/verify-2FA. See Authentication API and Verify 2FA.

Optional: Enroll a second credential (account setup)

After you already have an authenticated access_token, you may add another credential (for example phone):

POST /v1/users/credentials
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "type": "phone",
  "value": "+41791234567"
}

Then verify it:

POST /v1/users/verify-credential
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc",
  "credential_type": "phone",
  "otp": "253239"
}

This does not replace /v1/verify-2FA on subsequent logins when mfa_mode requires MFA.

Step 5: Refresh Token

1. Send a POST request to /v1/refresh-token
2. Headers:

   Authorization: Bearer {access_token}
   X-Device-ID: device_id_here
   X-App-ID: web-app
   Accept-Language: en

3. No request body. The refresh token travels in the HTTP-only cookie from login.
4. Expected Response (200 OK):

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "expires_in": 900,
     "idle_timeout_seconds": 900,
     "user_id": "3020dfc6-a073-4146-a594-3f11c5d6e4bc"
   }

Authorization must be a post-auth access_token (sub=user_auth). Sending challenge_token here returns 401.

Step 6: Logout

1. Send a POST request to /v1/logout
2. Headers:

   Authorization: Bearer your_access_token_here
   X-Device-ID: device_id_here
   Accept-Language: en  // Use 'de', 'fr', or 'it' for other supported languages

3. No request body is needed.
4. Expected Response (200 OK):

   {
     "status": 200,
     "message": "Logged out successfully"
   }

   Note: The refresh token cookie will be cleared during logout.

Important Notes

1. Language Localization:

   • Use the Accept-Language header to specify your preferred language for response messages.
   • Supported values are en (English), de (German), fr (French), and it (Italian).
   • If not specified, the system will default to English.

2. Security:

   • Always use HTTPS for all API communications.
   • Store the access token securely on the client-side.
   • The refresh token is automatically managed by the server using HTTP-only cookies.
   • Treat challenge_token as pre-auth only: use X-MFA-Challenge on /v1/verify-2FA (when enabled), or Authorization: Bearer {challenge_token} only on explicit TOTP setup routes. Never use it on protected APIs or refresh.

3. Device and app identity:

   • Use a consistent X-Device-ID for the same device across authentication, verify-2FA, and refresh.
   • Send X-App-ID (for example web-app) on authenticate, verify-2FA, and refresh so refresh cookies stay scoped per application.

4. Token Management:

   • The access token has a shorter lifespan (15 minutes by default) than the refresh token (14 days by default).
   • Implement logic to handle token expiration and refresh scenarios in your application.
   • If authentication fails (401 Unauthorized), attempt to refresh the token. If that fails, prompt the user to re-enter their credentials.

5. Error Handling:

   • Implement proper error handling for various HTTP status codes.
   • Pay attention to rate limiting and temporary lock-out scenarios, especially during authentication.

6. Compliance:

   • Ensure users accept the terms and conditions and privacy policy during registration.
   • Handle user data in compliance with relevant data protection regulations.

7. CORS (Cross-Origin Resource Sharing):

   • The API supports CORS for web applications.
   • Allowed headers include: Content-Type, Authorization, X-API-Key, X-Device-ID, X-App-ID, X-MFA-Challenge, Accept-Language.
   • Specific origins may be restricted based on server configuration.

By following these steps and best practices, you can implement a secure and localized user registration and authentication process in your application.