A string that uniquely identifies the user within your project. Ensure that
this is the ID that you use to identify the user in your system e.g. database
ID, Firebase Auth ID etc. Failing to do so may cause unexpected bugs and
errors in your application.
HMAC authentication is a mechanism that provides an additional layer of security to ensure your client
application can securely consume Proficient APIs. To enable HMAC authentication for a given project you
simply need to go the Project Settings page on the dashboard
and toggle it on.Once HMAC authentication is enabled, all Client API endpoints will require a X-PROFICIENT-USER-HMAC
header, and the requests that don’t include will be rejected with a 401 error.
While HMAC authentication is optional, we strongly recommend enabling it for
applications that have an authentication flow where user data is persisted
into your system. Disabling HMAC may pose a security risk where an end user
can access another user’s data.
The HMAC hash is a string generated with the SHA-256 algorithm and
digested with Base64. It is produced using your project’s HMAC secret as key and your user’s external ID
as message.
You can find the HMAC secret associated with your project in Project
Settings. It’s a string that
starts with hsec_.
The HMAC hash needs to be computed in your backend for each user. You can set up a small backend service
(e.g. a Firebase Cloud Function or AWS Lambda) where you authenticate your user and then proceed to
compute the hash with their unique ID.Summarizing the entire flow:
Your frontend sends a request to your backend with the user’s external ID.
Your backend authenticates the user using your authentication system.
Your backend computes the hash and sends it back to your frontend.
Your frontend can now access Proficient’s Client API with an additional X-PROFICIENT-USER-HMAC header.
Here is a simple example with a React application using the React SDK for
the frontend and a Node.js/Express application for the backend.
Copy
import { InteractionView } from "@proficient/react";import axios from "axios";async function retrieveHmacHash(userExternalId: string) { type Response = { hmac: string; }; const serverBaseUrl = "http://example.com"; // Replace with your own const { data } = await axios.request<Response>({ baseURL: `${serverBaseUrl}/hmac`, data: { userExternalId }, headers: { "Content-Type": "application/json", }, }); return data.hmac;}export default function App() { // Agent ID can be hardcoded or retrieved from the API const agentId = "ag_Lad8YCGGiDLiqIZPWRXmc2ix"; // User external ID should be accessed dynamically const userExternalId = "gtLIK8ELsHTr0Fajg28Ud9eFpJJ3"; return ( <div> <InteractionView // Your publishable API key that starts with `pk_` apiKey={process.env.PROFICIENT_API_KEY} agentId={agentId} userExternalId={userExternalId} userHmac={() => retrieveHmacHash(userExternalId)} /> </div> );}