Authentication
Use request headers for authentication
Authentication with the Client API is achieved with three request headers, one of which is optional depending on your project configuration.
Headers
The publishable API key associated with your project. You can find this in
Project Settings. It’s a string
that starts with pk_
.
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.
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:
- 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.
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.