All requests to the Naxai API must be authenticated through the Authorization header. The Naxai API offers the following authentication methods:

OAuth 2.0
Credentials in Header (not recommended)

Select your preferred method to suit your current tech stack and security requirement level. Many of these methods are vulnerable to man-in-the-middle attacks, so combining them with other security mechanisms, such as an encrypted connection or SSL is recommended.

📘
API Credentials
You can generate additional client credentials in your account settings (Integrations -> API Credentials). Follow our guide for more information.

OAuth 2.0

This type of authentication is the most secure option and is almost industry standard. You'll use an access token you get from a separate endpoint.

Here are some key facts about this method:

The access token returned in response will expire within the time limit provided in seconds in the same response.

A new token has to be created once the token expires - There is no automatic token retrieval For more details, see the official OAuth 2.0 specification.

How to use OAuth 2.0

Make a call to get the access token and the expiration time from a separate endpoint. Include "Bearer " and the token in the Authorization header for all subsequent calls until the token expires.

Authorization: Bearer eyJhcGciOiJSUzI1NiIsInR5...

HTTP Request

Obtain OAuth2 token

curl --location 'https://auth.naxai.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=DkMLm4ghpnx7wVoqiKYZSBTE1Zr16EdE' \
--data-urlencode 'client_secret=YNjm5x5lp9qymcJmL1AdfAia2YwUTN4ARSVC1jSsi6sp4ZOkvbFuKd1kRniBx_PD' \
--data-urlencode 'grant_type=client_credentials'

Get the token from access_token

{
    "access_token": "eyJhcGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNjdEwwV3AtNkMtYnk1NHlfM0k3UCJ9.eyJodHRwczovL3JpbmdyaW5nL2NsaWVudF9yZXNlbGxlcklkIjoiMSIsImh0dHBzOi8vcmluZ3JpbmcvY2xpZW50X05ld0N1c3RvbWVySWQiOiJlYTliMjM2OC1mMjgzLTQ5ODgtYmI0Ny1kZjA3MjJiN2Q3MDEiLCJodHRwczovL3JpbmdyaW5nL2NsaWVudF9vbGRDdXN0b21lcklkIjoiNzU2MCIsImh0dHBzOi8vcmluZ3Jpbmcvcm9sZSI6Ik93bmVyIiwicm9sZSI6Ik93bmVyIiwiaHR0cHM6Ly9yaW5ncmluZy91c2VyX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiaHR0cHM6Ly9yaW5ncmluZy9jbGllbnRfZW1haWwiOiJBUEkiLCJodHRwczovL3JpbmdyaW5nL2FwcGxpY2F0aW9uX2lkIjoiRGtNTG00Z2hwbng3d1ZvcWlLWVpTQlRFMVpyMTZFZEIiLCJpc3MiOiJodHRwczovL2xvZ2luLmRldi1uYXhhaS5jb20vIiwic3ViIjoiRGtNTG00Z2hwbng3d1ZvcWlLWVpTQlRFMVpyMTZFZEJAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vcmluZ3JpbmcuZGV2L3BvcnRhbCIsImlhdCI6MTY3ODc3OTAyNSwiZXhwIjoxNjc4ODY1NDI1LCJhenAiOiJEa01MbTRnaHBueDd3Vm9xaUtZWlNCVEUxWnIxNkVkQiIsInNjb3BlIjoicHJvZmlsZTp1c2VycyB3cml0ZTp1c2VycyByZWFkOmN1c3RvbWVycyB3cml0ZTpjdXN0b21lcnMgcmVhZDpjb250YWN0cyB3cml0ZTpjb250YWN0cyByZWFkOnVzZXJzIHJlYWQ6c2VhcmNoIHdyaXRlOnNlYXJjaCByZWFkOmVtYWlsc2V0dGluZ3Mgd3JpdGU6ZW1haWxzZXR0aW5ncyBzZW5kOmVtYWlsIHdyaXRlOnRlYW1zIHJlYWQ6dGVhbXMgcmVhZHNlbnNpdGl2ZTpjb250YWN0cyByZWFkOmNvbnRhY3RzLXNldHRpbmdzIHdyaXRlOmF1ZGllbmNlcyB3cml0ZTpmZWVkcyB3cml0ZTpzZWdtZW50cyB3cml0ZTphdHRyaWJ1dGVzIHdyaXRlOmNhbGVuZGFycyByZWFkOmNhbGVuZGFycyB3cml0ZTpzdXJ2ZXlzIHJlYWQ6c3VydmV5cyByZWFkOnN1cnZleXMtcmVwb3J0aW5nIHJlYWQ6YXVkaWVuY2VzIHdyaXRlOndlYmhvb2stbWFuYWdlciByZWFkOndlYmhvb2stbWFuYWdlciB3cml0ZTpjdXN0b21lcnMtc2V0dGluZ3MgcmVhZDpjdXN0b21lcnMtc2V0dGluZ3Mgd3JpdGU6dXNlcnNfdjIgcmVhZDp1c2Vyc192MiByZWFkOnNtcy10ZW1wbGF0ZXMgd3JpdGU6c21zLXRlbXBsYXRlcyByZWFkOnBpbmcgcmVhZDpjcmVkZW50aWFscyB3cml0ZTpjcmVkZW50aWFscyByZWFkOnBlb3BsZSB3cml0ZTpwZW9wbGUiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJwcm9maWxlOnVzZXJzIiwid3JpdGU6dXNlcnMiLCJyZWFkOmN1c3RvbWVycyIsIndyaXRlOmN1c3RvbWVycyIsInJlYWQ6Y29udGFjdHMiLCJ3cml0ZTpjb250YWN0cyIsInJlYWQ6dXNlcnMiLCJyZWFkOnNlYXJjaCIsIndyaXRlOnNlYXJjaCIsInJlYWQ6ZW1haWxzZXR0aW5ncyIsIndyaXRlOmVtYWlsc2V0dGluZ3MiLCJzZW5kOmVtYWlsIiwid3JpdGU6dGVhbXMiLCJyZWFkOnRlYW1zIiwicmVhZHNlbnNpdGl2ZTpjb250YWN0cyIsInJlYWQ6Y29udGFjdHMtc2V0dGluZ3MiLCJ3cml0ZTphdWRpZW5jZXMiLCJ3cml0ZTpmZWVkcyIsIndyaXRlOnNlZ21lbnRzIiwid3JpdGU6YXR0cmlidXRlcyIsIndyaXRlOmNhbGVuZGFycyIsInJlYWQ6Y2FsZW5kYXJzIiwid3JpdGU6c3VydmV5cyIsInJlYWQ6c3VydmV5cyIsInJlYWQ6c3VydmV5cy1yZXBvcnRpbmciLCJyZWFkOmF1ZGllbmNlcyIsIndyaXRlOndlYmhvb2stbWFuYWdlciIsInJlYWQ6d2ViaG9vay1tYW5hZ2VyIiwid3JpdGU6Y3VzdG9tZXJzLXNldHRpbmdzIiwicmVhZDpjdXN0b21lcnMtc2V0dGluZ3MiLCJ3cml0ZTp1c2Vyc192MiIsInJlYWQ6dXNlcnNfdjIiLCJyZWFkOnNtcy10ZW1wbGF0ZXMiLCJ3cml0ZTpzbXMtdGVtcGxhdGVzIiwicmVhZDpwaW5nIiwicmVhZDpjcmVkZW50aWFscyIsIndyaXRlOmNyZWRlbnRpYWxzIiwicmVhZDpwZW9wbGUiLCJ3cml0ZTpwZW9wbGUiXX0.zK12A2ongayYsXTbgyBAfZNA5cZPpu17P3Lu6uA0g4HxW4xvSmS-6kVtVg8XTqwYS25IxVsRyET7LSVBcoctw1DUW8FeB6cHVKVOjODGjLv5waXjV-DHiqPcWuL-xoxXughyZ4I4S5hWMFW5NoVzxNQBH4LMcqcdqiYWDxnrn3d_0M-bOwN8wOwV7t69h0qjMnEIRWbgADlpIhOwSn7_E5unSqWMPn4IMbOnr_uST-Y6NMJu6J42FBQ-nQrEZrGdbgtLVfUlyAeBXf2NrbRG5MYuFlIuPXY-wGz0B7XL_jTJdJqlKT0EjfcizFZaHg6bT6FQNx5wtFtLOpr6kKyZgg",
    "scope": "profile:users write:users read:customers write:customers read:contacts write:contacts read:users read:search write:search read:emailsettings write:emailsettings send:email write:teams read:teams readsensitive:contacts read:contacts-settings write:audiences write:feeds write:segments write:attributes write:calendars read:calendars write:surveys read:surveys read:surveys-reporting read:audiences write:webhook-manager read:webhook-manager write:customers-settings read:customers-settings write:users_v2 read:users_v2 read:sms-templates write:sms-templates read:ping read:credentials write:credentials read:people write:people",
    "expires_in": 85459,
    "token_type": "Bearer"
}

Use the token in a subsequent request by adding the token to the header.

You can use our ping endpoint; you should receive an HTTP status 200.

curl --location 'https://api.naxai.com/ping' \
--header 'Authorization: Bearer eyJhcGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNjdEwwV3AtNkMtYnk1NHlfM0k3UCJ9.eyJodHRwczovL3JpbmdyaW5nL2NsaWVudF9yZXNlbGxlcklkIjoiMSIsImh0dHBzOi8vcmluZ3JpbmcvY2xpZW50X05ld0N1c3RvbWVySWQiOiJlYTliMjM2OC1mMjgzLTQ5ODgtYmI0Ny1kZjA3MjJiN2Q3MDEiLCJodHRwczovL3JpbmdyaW5nL2NsaWVudF9vbGRDdXN0b21lcklkIjoiNzU2MCIsImh0dHBzOi8vcmluZ3Jpbmcvcm9sZSI6Ik93bmVyIiwicm9sZSI6Ik93bmVyIiwiaHR0cHM6Ly9yaW5ncmluZy91c2VyX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiaHR0cHM6Ly9yaW5ncmluZy9jbGllbnRfZW1haWwiOiJBUEkiLCJodHRwczovL3JpbmdyaW5nL2FwcGxpY2F0aW9uX2lkIjoiRGtNTG00Z2hwbng3d1ZvcWlLWVpTQlRFMVpyMTZFZEIiLCJpc3MiOiJodHRwczovL2xvZ2luLmRldi1uYXhhaS5jb20vIiwic3ViIjoiRGtNTG00Z2hwbng3d1ZvcWlLWVpTQlRFMVpyMTZFZEJAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vcmluZ3JpbmcuZGV2L3BvcnRhbCIsImlhdCI6MTY3ODc3OTAyNSwiZXhwIjoxNjc4ODY1NDI1LCJhenAiOiJEa01MbTRnaHBueDd3Vm9xaUtZWlNCVEUxWnIxNkVkQiIsInNjb3BlIjoicHJvZmlsZTp1c2VycyB3cml0ZTp1c2VycyByZWFkOmN1c3RvbWVycyB3cml0ZTpjdXN0b21lcnMgcmVhZDpjb250YWN0cyB3cml0ZTpjb250YWN0cyByZWFkOnVzZXJzIHJlYWQ6c2VhcmNoIHdyaXRlOnNlYXJjaCByZWFkOmVtYWlsc2V0dGluZ3Mgd3JpdGU6ZW1haWxzZXR0aW5ncyBzZW5kOmVtYWlsIHdyaXRlOnRlYW1zIHJlYWQ6dGVhbXMgcmVhZHNlbnNpdGl2ZTpjb250YWN0cyByZWFkOmNvbnRhY3RzLXNldHRpbmdzIHdyaXRlOmF1ZGllbmNlcyB3cml0ZTpmZWVkcyB3cml0ZTpzZWdtZW50cyB3cml0ZTphdHRyaWJ1dGVzIHdyaXRlOmNhbGVuZGFycyByZWFkOmNhbGVuZGFycyB3cml0ZTpzdXJ2ZXlzIHJlYWQ6c3VydmV5cyByZWFkOnN1cnZleXMtcmVwb3J0aW5nIHJlYWQ6YXVkaWVuY2VzIHdyaXRlOndlYmhvb2stbWFuYWdlciByZWFkOndlYmhvb2stbWFuYWdlciB3cml0ZTpjdXN0b21lcnMtc2V0dGluZ3MgcmVhZDpjdXN0b21lcnMtc2V0dGluZ3Mgd3JpdGU6dXNlcnNfdjIgcmVhZDp1c2Vyc192MiByZWFkOnNtcy10ZW1wbGF0ZXMgd3JpdGU6c21zLXRlbXBsYXRlcyByZWFkOnBpbmcgcmVhZDpjcmVkZW50aWFscyB3cml0ZTpjcmVkZW50aWFscyByZWFkOnBlb3BsZSB3cml0ZTpwZW9wbGUiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJwcm9maWxlOnVzZXJzIiwid3JpdGU6dXNlcnMiLCJyZWFkOmN1c3RvbWVycyIsIndyaXRlOmN1c3RvbWVycyIsInJlYWQ6Y29udGFjdHMiLCJ3cml0ZTpjb250YWN0cyIsInJlYWQ6dXNlcnMiLCJyZWFkOnNlYXJjaCIsIndyaXRlOnNlYXJjaCIsInJlYWQ6ZW1haWxzZXR0aW5ncyIsIndyaXRlOmVtYWlsc2V0dGluZ3MiLCJzZW5kOmVtYWlsIiwid3JpdGU6dGVhbXMiLCJyZWFkOnRlYW1zIiwicmVhZHNlbnNpdGl2ZTpjb250YWN0cyIsInJlYWQ6Y29udGFjdHMtc2V0dGluZ3MiLCJ3cml0ZTphdWRpZW5jZXMiLCJ3cml0ZTpmZWVkcyIsIndyaXRlOnNlZ21lbnRzIiwid3JpdGU6YXR0cmlidXRlcyIsIndyaXRlOmNhbGVuZGFycyIsInJlYWQ6Y2FsZW5kYXJzIiwid3JpdGU6c3VydmV5cyIsInJlYWQ6c3VydmV5cyIsInJlYWQ6c3VydmV5cy1yZXBvcnRpbmciLCJyZWFkOmF1ZGllbmNlcyIsIndyaXRlOndlYmhvb2stbWFuYWdlciIsInJlYWQ6d2ViaG9vay1tYW5hZ2VyIiwid3JpdGU6Y3VzdG9tZXJzLXNldHRpbmdzIiwicmVhZDpjdXN0b21lcnMtc2V0dGluZ3MiLCJ3cml0ZTp1c2Vyc192MiIsInJlYWQ6dXNlcnNfdjIiLCJyZWFkOnNtcy10ZW1wbGF0ZXMiLCJ3cml0ZTpzbXMtdGVtcGxhdGVzIiwicmVhZDpwaW5nIiwicmVhZDpjcmVkZW50aWFscyIsIndyaXRlOmNyZWRlbnRpYWxzIiwicmVhZDpwZW9wbGUiLCJ3cml0ZTpwZW9wbGUiXX0.zK12A2ongayYsXTbgyBAfZNA5cZPpu17P3Lu6uA0g4HxW4xvSmS-6kVtVg8XTqwYS25IxVsRyET7LSVBcoctw1DUW8FeB6cHVKVOjODGjLv5waXjV-DHiqPcWuL-xoxXughyZ4I4S5hWMFW5NoVzxNQBH4LMcqcdqiYWDxnrn3d_0M-bOwN8wOwV7t69h0qjMnEIRWbgADlpIhOwSn7_E5unSqWMPn4IMbOnr_uST-Y6NMJu6J42FBQ-nQrEZrGdbgtLVfUlyAeBXf2NrbRG5MYuFlIuPXY-wGz0B7XL_jTJdJqlKT0EjfcizFZaHg6bT6FQNx5wtFtLOpr6kKyZgg'

Token Refresh: How and When

Access tokens issued by Naxai are short-lived (24 hours) for security reasons. To maintain uninterrupted access to protected resources, you should refresh the token before it expires. The recommended approach is:

Use the refresh token provided during initial authentication.
Trigger a refresh when:
- You receive a 401 Unauthorized response due to token expiry.
- Your application detects that the token is nearing its expiry time (e.g., within 5 minutes).
Avoid refreshing too frequently to reduce load and prevent rate limiting.

Credentials in Header

Client Id and Secret can be passed in the header of every request using the headers: X-Client-Id and X-Client-Secret.

Naxai doesn't recommend this method, but we understand that some Iot devices or specific applications cannot manage the Client Credentials flow of OAuth2.

When using this authentication method, we recommend you create an additional Client Id and Secret pair available on your account settings page.