Skip to main content
POST
/
api
/
v1
/
auth
/
ensure-user
Ensure User Creation
curl --request POST \
  --url https://api.example.com/api/v1/auth/ensure-user
{
  "success": true,
  "message": "User ensured in Engine and DBStorage"
}
Forces the creation of a user in the Engine and Database Storage services. This endpoint is useful for ensuring a user exists across all system components, even if they were already in the database.

​
Authentication

This endpoint requires authentication via JWT token in the Authorization header. 
Authorization: Bearer <your_jwt_token>

​
Request Body

This endpoint does not accept a request body. The user ID and email are extracted from the JWT token.

​
Response

​
success
boolean
Indicates if the operation was successful
​
message
string
Description of the result

​
Examples

​
Successful Request

curl -X POST "http://localhost:8000/api/v1/auth/ensure-user" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "success": true,
  "message": "User ensured in Engine and DBStorage"
}

​
User Creation Initiated

{
  "success": true,
  "message": "User creation initiated"
}

​
Error Responses

​
Error: No Token Provided

{
  "error": "No token provided."
}

​
Error: Invalid Token

{
  "error": "Invalid or expired token."
}

​
Error: Invalid Token Payload

{
  "error": "Invalid token payload."
}

​
Error: Failed to Ensure User

{
  "error": "Failed to ensure user, but request was sent to Engine"
}

​
Implementation Details

This endpoint:
  1. Extracts User Info: Gets user ID and email from the JWT token
  2. Sends Creation Request: Always sends a createUser message to Redis Streams
  3. Waits for Response: Waits up to 5 seconds for confirmation from the Engine
  4. Returns Status: Confirms whether the user was ensured in all services

​
Difference from verify-user

Unlike /verify-user, this endpoint always sends the user creation request to the Engine, regardless of whether the user exists in the database. This ensures consistency across all system components.

​
Use Cases

​
System Recovery

Use this endpoint to recover from system inconsistencies where a user exists in the database but not in the Engine: 
const recoverUserState = async (token) => {
  try {
    const result = await fetch('http://localhost:8000/api/v1/auth/ensure-user', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` }
    });
    
    const data = await result.json();
    
    if (data.success) {
      console.log('User state synchronized across all services');
      return true;
    }
    
    return false;
  } catch (error) {
    console.error('Failed to ensure user:', error);
    return false;
  }
};

​
First-Time Setup

Call this endpoint during user onboarding to ensure the user is properly initialized: 
const onboardNewUser = async (token) => {
  // Step 1: Ensure user is created in all services
  const ensureResult = await fetch('http://localhost:8000/api/v1/auth/ensure-user', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  if (!ensureResult.ok) {
    throw new Error('Failed to initialize user');
  }
  
  // Step 2: Proceed with onboarding
  return { ready: true };
};
  • Login - Initiate authentication flow
  • Verify - Complete email verification
  • Verify User - Check if user exists

Build docs developers (and LLMs) love

Get started for freeTalk to us