> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corebanq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User registration and authentication

# 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:
   ```json theme={null}
   {
     "credential_type": "email",
     "credential_value": "jane.smith@example.com",
     "password": "securePassword123!",
     "terms_accepted": true,
     "privacy_policy_accepted": true
   }
   ```
4. Expected Response (200 OK):
   ```json theme={null}
   {
     "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:
   ```json theme={null}
   {
     "user_id": "12345678-1234-1234-1234-123456789012",
     "credential_type": "email",
     "otp": "123456"
   }
   ```
4. Expected Response (200 OK):
   ```json theme={null}
   {
     "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:
   ```json theme={null}
   {
     "username": "jane.smith@example.com",
     "password": "securePassword123!"
   }
   ```
4. Expected Response (200 OK):
   ```json theme={null}
   {
     "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:

```http theme={null}
POST /v1/users/credentials
Content-Type: application/json
Authorization: Bearer your_access_token_here

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

2. Verify the phone credential:

```http theme={null}
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"
}
```

<Note>
  Once a second credential is verified, 2FA will be automatically activated. For subsequent logins, after password authentication, you'll need to complete 2FA verification. See [Authentication API](/api-reference/authentication/auth) for details.
</Note>

## 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):
   ```json theme={null}
   {
     "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):
   ```json theme={null}
   {
     "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.