We released the Alexa Voice Service (AVS) sample app on GitHub last year, equipping developers with the technology to build their own voice-enabled prototypes with a Raspberry Pi and Amazon Alexa. Since then we’ve regularly improved upon the app to make it easier for Alexa developers to test new features, such as hands-free voice control, and prototype with language and region-specific services in the UK and Germany.
Today we’re releasing some updates to the AVS sample app that you can take advantage of right away!
Persisting Access Tokens with the AVS Sample App
We’ve been listening to the developer community, and one of the most requested features we receive is the ability to preserve your login status when using the Node.js authentication service. In previous versions of the sample app, you would need to re-authenticate with your Amazon.com credentials every time you restarted the java sample app and Node.js service. With today’s update, the Node.js service will now save the refresh token it gets from Login With Amazon (LWA) to disk, ensuring that you only need to login once.
With this change, it makes sense to explain how the login flow works in the AVS sample app. When you start the AVS sample app and the Node.js service for the first time, the sample app connects to the service in order to register itself. When the Node.js service receives this register request, it generates a registration code and a session identifier. This session ID is used for the lifetime of the service, allowing it to keep track of the refresh token, access token, and device information corresponding to a particular device and user. It then returns the session ID and registration to the AVS sample app. The AVS sample app uses the registration code to generate a URL for a user to authenticate.
When a user visits the URL in their browser, the Node.js service silently redirects them to LWA, where they can authenticate and authorize Amazon Alexa. LWA then redirects the user back to the Node.js service, passing along a refresh token. At this point, it’s important to clarify the difference between refresh tokens and access tokens.
Access tokens are the actual tokens used to authenticate a user to AVS, and for security reasons, they expire after an hour. When the tokens expire, users need to fetch a new access token from LWA. To obtain an access token, you must give LWA your refresh token. If the refresh token is valid, LWA will return a new access token, allowing you to continue to use AVS.
Now that the Node.js service has a refresh token, it can use it to retrieve the access tokens as needed. After getting the access token, the Node.js service associates it with the session ID that was generated for the device, and the sample app can retrieve the access token using the session ID that it received during the initial registration.
With today's update, the AVS sample app can now request a new token at any time using the session ID. The Node.js service will silently retrieve refresh tokens associated with that session ID, and request a new access token from LWA. As previously mentioned, this release persists the refresh token to disk, ensuring that the session ID remains valid between restarts, and that your experience using the AVS sample app is seamless after the initial authentication.
Things You Should Know
Two notes to understand regarding this update:
- Users still need to run the Node.js service in conjunction with the java sample app (this hasn’t changed).
- Users who wish to log out of the java sample app can refer to this workaround.
In addition to this update, we’ve also made some minor changes to the project, including new image assets in the app and we highlight the latest KITT.AI language hosted on their GitHub repository. Finally, we’ve addressed a few bugs—you can see the release notes for complete details.
Try It Yourself!
Pull down the latest version of the AVS sample app and give the project a go! New to AVS? Visit our Getting Started Guide to create an AVS developer account and start prototyping.
Have questions? We’re here to help. Visit us on the AVS Forum or Alexa GitHub to speak with one of our experts.