Authenticate User

When integrating your CRM with DealHub, the first step is setting up user authentication. This ensures that your sales team can securely access DealHub's features directly from your CRM. Once authenticated, users can create quotes, manage opportunities, and access all DealHub CPQ features seamlessly.

How Authentication Works

DealHub uses a two-step authentication process to keep your data secure while maintaining a smooth user experience. When a user tries to access DealHub features from your CRM:

1. Your system makes an authentication request using your permanent secret token (provided by your DealHub admin)
2. DealHub validates the request and returns a short-lived access token
3. You use this access token for the next 60 seconds to make any additional API calls

📘

Tip

New to DealHub? Your administrator can find the secret token in the DealHub CPQ Admin Panel under Integrations or API Settings.

Setting Up Authentication

Before you start implementing authentication, you'll need:

• A secret token from your DealHub CPQ administrator
• User information from your CRM system
• A secure way to store and manage tokens

Your DealHub administrator can generate the secret token from the CPQ Admin Panel. This token is permanent and should be stored securely - never expose it in client-side code or public repositories.

Making Authentication Requests

To authenticate a user, you'll make a POST request to DealHub's authentication endpoint. Here's a complete guide:

Endpoint Details

URL: /api/v1/user/authenticate

Method: POST

Headers:

Authorization: Bearer <YOUR_SECRET_TOKEN>
Content-Type: application/json

Request Body

The authentication request needs information about the user. Here's what you need to include:

{
  "user_information": {
    "external_user_id": "CRM123",        // Your CRM's user ID
    "email": "[email protected]",        // User's email
    "name": "Sarah Johnson",             // Full name
    "position": "Sales Representative",   // Job title (optional)
    "phone": "555-0123",                 // Phone number (optional)
    "company": "Tech Solutions Inc"       // Company name (optional)
  }
}

Let's look at each field in detail:

Required fields that you must include:

• external_user_id: Your CRM's unique identifier for the user (max 200 characters)
• email: The user's primary email address (max 100 characters)
• name: The user's full name as shown in your CRM (max 300 characters)

Optional fields that enhance the user experience:

• position: User's job title or role (max 300 characters)
• phone or mobile: Contact numbers (max 50/100 characters)
• company: Organization name (max 100 characters)
• Address fields: street, city, state, country, postal_code

❗️

Warning

Always validate field lengths before sending. Exceeding maximum lengths will cause authentication to fail.

Response Format

When the authentication is successful, you'll receive:

{
  "access_token": "4D114DAD97361C84B154A828FF991",
  "dealhub_user_id": "555455484454",
  "errors": []
}

The response includes:

• An access token valid for 60 seconds
• A DealHub user ID for future reference
• An empty errors array (or error messages if something went wrong)

Using the Authentication Response

Once you receive a successful response, you'll want to:

1. Store the access token securely - you'll need it for your next API call
2. Keep track of when you received it - it's only valid for 60 seconds
3. Save the DealHub user ID - you'll need it for most API calls

Here's a practical example of handling the response:

async function handleAuthResponse(response) {
  if (response.access_token) {
    // Store token with expiration time
    const expirationTime = Date.now() + 60000; // 60 seconds from now
    storeToken(response.access_token, expirationTime);
    
    // Store DealHub user ID
    storeUserId(response.dealhub_user_id);
    
    return true;
  }
  
  // Handle authentication failure
  console.error('Authentication failed:', response.errors);
  return false;
}

📘

Tip

Consider implementing a buffer time (e.g., 55 seconds instead of 60) to account for network latency when checking token expiration.

What Happens Behind the Scenes

When you authenticate a user, DealHub automatically:

1. Checks if the user exists (based on email or external_user_id)
2. Creates a new user account if they don't exist
3. Updates user information if the user exists
4. Assigns the "Sales" role to new users

This automatic user management means you don't need to manually create or update user accounts in DealHub.

Best Practices

Keep these guidelines in mind when implementing authentication:

Store tokens securely. Never save the permanent secret token in client-side code or expose it in network requests visible to users.

Always implement proper error handling. Users should see meaningful messages when authentication fails, not technical errors.

Keep your implementation maintainable by logging authentication attempts and monitoring for patterns in failures.

📘

Tip

Looking to implement your first quote creation? Head to the Create Quotes guide once you have authentication working.

Next steps

Now that you learned how to authenticate a user, learn how to create or open a new quote