Authorization

Local API endpoints require authorization. This article shows how to get authorized to use Nureva's local endpoints.

Accounts

Permissions required will vary, depending on the type of account. See the two account types below, listed in order of fewest permissions required to most permissions required.

1. general account: Includes monitoring data streams, day-to-day operations such as audio settings, room configuration, and integration configuration.

   By default for HDL310, HDL410, and HDX, the password is the enrollment code which has the XXX-XXX-XXX format. Existing HDL310 and 410 deployments continue to have blank password until a factory reset is performed.

   For security, it is recommended to update HDL310/HDL410 password from the blank default. For more information on updating the general password, go to third-party integration password.

2. admin account: Includes all permissions from general account plus configuring security policies.

   By default for HDL310, HDL410, and HDX, the password is the enrollment code which has the XXX-XXX-XXX format. Performing a factory reset will set the password to enrollment code.

   For more information on resetting the password, go to HDL310/HDL410 password or HDX password.

How to authenticate

Local API endpoints require an authorization header. For third-party integration apps, it is recommended to use the general account.

Use the login endpoint with the general account to retrieve the authParameters needed for authorization. In the case that the account password changes, run the login endpoint again to refresh authorization parameters.

1. Set the path with the IP address of the Nureva device followed by /api/v1/auth/login.
2. Update the request body to include the account property with general as the value. Note: the account value is case-sensitive and should be lowercase.
3. Update the request body to include the password property with the sample password of integration123 as the value. (By default, the password is either blank or set to the enrollment code. A custom password can be configured through the Nureva app.)
4. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
5. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
6. Update the headers to include Content-Type as key and application/json as the value.
7. Send the POST request. The code sample below is a request to retrieve the authorization header.

curl --request POST \
     --url https://10.0.0.1/api/v1/auth/login \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1' \
     --header 'Content-Type: application/json' \
     --data '{"account": "general", "password": "integration123"}'

8. A successful response with the above name and password would return the following. If authentication fails, please refer to the error responses documented here.

{
  "authParameters": "Z2VuZXJhbDppbnRlZ3JhdGlvbjEyMw=="
}

9. From the response, set the Authorization header to Nureva followed by the value received in authParameters for all authenticated endpoints, like in the example below.

curl --request GET \
     --url https://10.0.0.1/api/v1/audio \
     --header 'Authorization: Nureva Z2VuZXJhbDppbnRlZ3JhdGlvbjEyMw==' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'

The interactive console in the API reference also provides an easy way to try out the endpoints.

✅

Tutorial complete!

You now know how to authenticate.