A JSON Web Token, or JWT, authorizes your application code to securely connect to your unique Spatial Audio API Space.
Project Complexity: ★★☆☆☆
JWTs are an open industry standard method for securely representing claims between two parties. Click here to learn more about JWTs. (Link will open in a new tab)
In this guide, you will learn how to:
If you already have a High Fidelity Developer Account, you can jump straight to the next step.
Before your app can make use of the Spatial Audio API, you'll need a High Fidelity Developer Account. Sign up for an account or log in here.
No matter the method you use to generate a JSON Web Token for use with the Spatial Audio API, you will need to first create an App, then at least one Space associated with that App. To do that:
Do not share the data you see on this page. It allows users to make authorized connections to your High Fidelity Spatial Audio Server.
It can be useful to obtain a test JWT to make sure that your test applications can connect to the Spatial Audio API Servers.
Do not use Test JWTs generated using this method for production applications. To learn how to generate JWTs for production environments, skip to the next step.
To get a Test JWT:
The long string that is generated is your Test JSON Web Token (JWT). You can use this Test JWT for testing your applications, such as the one you can build by following the "Build a Simple Web App" guide.
Do not share this JWT. It allows users to make authorized connections to your High Fidelity Spatial Audio Server.
Your JWT should look something like this sample JWT (this sample won't work in any of your apps):
In your application's production environment, each client running your app code should connect to the High Fidelity Spatial Audio Server with a unique JWT.
In the case of a Web application, your application server code should generate a JWT associated with the user requesting your Web application. There is almost certainly a library available for your server's language - check out jwt.io/#libraries-io to find a library relevant to you.
We recommend that your production application create JWTs with an expiration time. A JWT without an expiry value can be re-used as the API has no way of knowing if it is a legitimate JWT or a stolen JWT. Once the expiration time has passed, the token is no longer valid. Common practice is to make the expiry time relatively short - ~15 minutes - so that any compromised JWTs will cease to be valid quickly.
We have learned that the High Fidelity API uses JWTs to authenticate and direct incoming connections into your Spaces. These JWTs are generated by making use of the following pieces of information:
Do not share the data you see on this page. It allows users to make authorized connections to your High Fidelity Spatial Audio Server. If you accidentally expose your App Secret, you can regenerate one from the App Details page in the Developer Console.
Next, we will detail how to generate a Spatial Audio API JWT using
NodeJS. Before we dive in to the details, here's the most basic version of the NodeJS code used to generate a JWT:
To complete this guide, you will need to install the following software on your computer:
Next, let's create a skeleton version of a NodeJS project we'll use for development:
Create a new folder on your local disk that you'll use for development, such as
cdinto that development directory.
npm initto initialize a new NodeJS project, inputting data as prompted. The data you input isn't important for the purposes of this guide.
npm install firstname.lastname@example.org
npm install jose
joseis a package used to create JWTs using NodeJS.
Inside your development directory, create a new file called
index.js. This is where we'll write our code.
Now, we are going to write some NodeJS code! When executed, this code will create a new JWT, securely sign it, and then connect to the Spatial Audio API Server.
index.js in your favorite code editor.
Now, let's add to this file almost all of the code necessary to make this sample app work. Copy and paste the following code into
At this point, you'll need to find the App ID, Space ID, and App Secret associated with the App and Space that you created above.
index.js file, paste your App ID inside the quotes on the line
const APP_ID = "aaaaaaaa-1111-bbbb-2222-cccccccccccc";. Do the same for your Space ID and App Secret.
index.js file, set a User ID inside the quotes on the line
const USER_ID = "steve";.
In this example code, we are statically setting the
user_id field of the JWT. In production environments, the
user_id field of the JWT should be set dynamically based on the identity of the user using a given instance of your application.
Almost there! Let's run the code that we just wrote to make sure that it works.
cdinto your development directory.
node index.jsand press enter.
If you see
Successfully connected to HiFi Audio API Server! in the logs that appear, everything is working!
For detailed technical information about the High Fidelity Spatial Audio Client API, visit the API documentation.
If you have any questions or comments, please reach out to email@example.com.