​

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
   Accept-Language: en
   

3. Request Body:

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

4. Expected Response (200 OK):

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

​

Step 4: Verify 2FA (When Required)

2FA is automatically activated after verifying a second credential:

1. Add a phone credential:

POST /v1/users/credentials
Content-Type: application/json
Authorization: Bearer your_access_token_here

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

2. Verify the phone credential:

POST /v1/users/verify-credential
Content-Type: application/json
Authorization: Bearer your_access_token_here

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

​

Step 5: Refresh Token

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

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

3. No request body is needed. The refresh token is automatically included via the HTTP-only cookie set during authentication.
4. Expected Response (200 OK):

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

   Note: A new refresh token will be set as an HTTP-only cookie in the response.

​

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.

3. Device Identification:

   • Use a consistent X-Device-ID for the same device across all requests.
   • This is crucial for security, especially during authentication and token refresh operations.

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, 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.