Authenticate Partner User

The PRM server sends this request to DealHub to authenticate a partner user and obtain a short-lived access token. This is the first of two requests in the Partner API flow and must always originate from the server side. Because the request body contains the DealHub authentication key, sending it from the browser exposes the key to interception.

Prerequisites

The Partner API requires both a valid credential generated in DealHub and a server-side execution environment on the PRM side:

• DealHub Authentication Key: A CPQ administrator must have already enabled the Partner API and generated an authentication key in System Settings > API Settings. The key is displayed only once at generation time. If you do not have it, ask your DealHub admin to generate a new one.
• Server-side execution environment: The PRM application must have a backend capable of making server-to-server HTTP requests. This request cannot be sent from the browser.

The Authentication Workflow

Each time a partner user initiates a session, the PRM application must complete the following sequence:

1. Send the authentication request from the PRM server to DealHub, including the authentication key and user information.
2. Receive the access token from DealHub. The token is valid for 60 seconds and is single-use.
3. Pass the token to the client and immediately trigger the Open DealHub CPQ request from the browser.

Step 1: Send the Authentication Request

Send a POST request to /api/v1/authenticate/user from the PRM server. Include the DealHub authentication key and the partner user's details in the request body.

🚧

Always send this request from the server

The request body contains your long-lived DealHub authentication key. If this request originates from the browser, the key can be read from cookies or intercepted in transit and used to access your DealHub account. Never send this request from the client side.

Method: POST

URL: /api/v1/authenticate/user

Request body:

{
  "authentication": "480zZQNXR8zoTicG.7MIkom0ETwBjYWzi",
  "user_information": {
    "type": "partner",
    "user_id": "qwerty1234356",
    "login": "[email protected]@acmepartner",
    "email": "[email protected]",
    "name": "David Solomon",
    "position": "Sales",
    "phone": "03-12345678",
    "mobile": "058-12345678",
    "fax": "03-12345679",
    "company": "Acme Partner1",
    "street": "12nd Broadway",
    "city": "New York",
    "state": "NY",
    "country": "USA",
    "postal_code": "1234567",
    "profile_img": "https://domain.com/img.png"
  }
}

Parameters:

🚧

The login field must be unique across all DealHub tenants, not just within your own account. If a partner user works with multiple companies that each use DealHub, only the first tenant to register that login will succeed. To avoid collisions, use a composite format: USER_EMAIL@{company_name}. For example: [email protected]@acmepartner. Apply the same logic to sandbox environments by appending a suffix such as _sb to sandbox logins.

📘

First-time users are created automatically

If no user with the given login exists in DealHub, DealHub creates the user record automatically using the provided user_information fields. Include optional fields such as position, company, and phone on the first call. These fields are written at creation time and cannot be updated later via this API.

Step 2: Use the Access Token

A successful request returns HTTP 200 and a one-time access token.

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

Pass the access_token to the PRM client immediately and trigger the Open DealHub CPQ request from the browser without delay.

❗️

Token expiry

The access token expires after 60 seconds and is single-use. It cannot be reused across sessions. If the token expires before it is consumed, send the authentication request again to obtain a new one.

Best Practices

The request body contains your long-lived DealHub authentication key. If the request originates from the client side, the key can be read from cookies or intercepted in transit and used to extract sensitive business data from your DealHub account. Thus, always send this request from the PRM server, not the browser.

The login field must be globally unique across all DealHub tenants, not just within your own account. If a partner user works with multiple companies that each use DealHub, only the first tenant to register that login will succeed, subsequent attempts for the same login from a different tenant will fail. To avoid collisions, use a composite format such as USER_EMAIL@{company_name}. For example: [email protected]@acmepartner.

DealHub creates the user automatically on the first successful authentication. Optional fields such as name, company, phone, and position are written to the user record at creation time. If you omit them initially, you cannot update them later via the API.

The access_token returned in the response is single-use and expires after 60 seconds. Pass it to the client side immediately and trigger the Open DealHub CPQ request without delay. If the token expires before use, run the authentication request again to obtain a new one.

Each time a partner user initiates a session, issue a fresh authentication request. Access tokens are one-time-use and cannot be reused even if they have not yet expired.

Next Steps

With the access token in hand, the PRM client can now redirect the partner user to create or view a quote: Open DealHub CPQ.

📘

Related API Reference

The Authenticate Partner User API Reference page documents the endpoint used in this guide.