Authentication with the Client API is achieved with three request headers, one of which is optional depending on your project configuration.

​
Headers

X-PROFICIENT-API-KEY
string
required

The publishable API key associated with your project. You can find this in Project Settings. It’s a string that starts with pk_.

X-PROFICIENT-USER-EXTERNAL-ID
string
required

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.

X-PROFICIENT-USER-HMAC
string

The HMAC hash for the user. See HMAC Authentication for more details.

Here is an example cURL request containing two auth headers:

​
HMAC Authentication

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.

​
Computing the HMAC hash

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:

  1. Your frontend sends a request to your backend with the user’s external ID.
  2. Your backend authenticates the user using your authentication system.
  3. Your backend computes the hash and sends it back to your frontend.
  4. Your frontend can now access Proficient’s Client API with an additional X-PROFICIENT-USER-HMAC header.

​
React + Node.js Example

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.

IntroductionSpecification