We recently launched the Alexa Lighting API extending Alexa’s built-in lighting skill so she can securely control cloud-connected lighting and switch devices. This new API enables you to write code that translates between Alexa’s built-in lighting skill and your lighting device’s proprietary control systems. Once a customer turns on the functionality, they can control these new devices simply by saying phrases like, “Alexa, turn on the living room lights” or "Alexa, turn off the fan." 

The Alexa Lighting API can be used to control any cloud-connected device that can be turned on/off or have its brightness adjusted. Discoverability is easy! Devices that you enable automatically show up in the Alexa companion app in the Connected Home settings screen. Wink and Samsung SmartThings have already built this functionality for their home automation hubs using the Alexa Lighting API, and any new devices you integrate will show up right alongside those!

In order to get things started a customer will need to connect their desired device to your skill adapter in the Alexa companion app. This process is handled via standard OAuth providers, like Login with Amazon, to make the experience as simple as possible.

Linking a New Customer Device via OAuth

Once you have followed the steps to submit a new skill adapter and have provisioned it for testing, a customer will see your skill adapter in their Alexa Companion App’s Connected Home settings screen.

In the above screenshot the linking workflow is initiated when a customer clicks on Link with My Virtual Devices. The customer is then redirected to the OAuth provider’s web portal to sign in.

The authentication workflow during customer linking breaks down as follows:

 

1. A customer clicks on “Link with My Virtual Device” in the Alexa Companion App

2. The Alexa Companion App redirects the customer to the OAuth provider, where the customer will be asked to enter their credentials

3. The standard OAuth workflow will then take place between the OAuth provider and Alexa services.

4. Alexa services will receive an AuthToken that is valid for the customer

5. Alexa Companion App will display a success message to the customer

After a customer has linked their account via an OAuth provider they are ready to start interacting with your skill adapter! As soon as a customer invokes device discovery by saying something like “Alexa, discover my devices” the following workflow will occur:
 

1. Alexa sends the discovery message along with the AuthToken (representing the customer) to the your skill adapter

2. Your skill adapter requests AuthToken validation from the OAuth provider

3. The OAuth provider responds with validation

4. Your skill adapter can now perform its discovery and return the list of discovered devices to Alexa

Using Login with Amazon as your OAuth provider

You can setup Login with Amazon as your skill adapter’s OAuth provider in just a few steps:

1. Create a new Login with Amazon security profile

2. Obtain your OAuth credentials

3. Set Login with Amazon as the OAuth provider for the Alexa Connected Home skill.

 Step 1 - Create a New Security profile

To create a new security profile on Login with Amazon, go the Developer Console and navigate to Login with Amazon by clicking on Apps & Services. Once you are on the Login with Amazon developer console page, click the Create a New Security Profile button.

Fill in the required information and hit Save.

Step 2 - Obtain Your OAuth Credentials

Your newly created security profile will now be available in the list of Login with Amazon Configurations.

You will receive the Client ID and Client Secret.  Please include this information when you submit your skill adapter for test provisioning.

 Click Show.

Step 3 - Whitelist Your Alexa Connected Home Skill

Next, we need to whitelist the Alexa Connected Home skill’s endpoints within your Login with Amazon security profile.  First, enter the Web Settings of your security profile:

 Next, click Edit on the page, and enter the following data:

• Allowed Origins: https://amazon.com
• Allowed Return URLs: https://pitangui.amazon.com/partner-authorization/establish

Hit Save.

Submitting Your Alexa Connected Home Skill

Congratulations, you have now configured Login with Amazon as an OAuth provider that will allow customers to easily login and authenticate to your skill.  Finally, you will need to write a cloud end point (using AWS Lambda or similar service) that will handle commands coming from Alexa CoHo, and route them to your own back-end services or device. Be sure to check out the Alexa CoHo showcase for sample skill adapter code that can get you started. Once you have completed the cloud endpoint you are ready to submit your skill adapter. Gather all of the required information outlined in the Getting Started section of the Alexa Lightning API Documentation and email the Alexa CoHo submissions team. We look forward to seeing what you build!

You may also want to check out these additional Alexa developer resources for more information:

Order Echo - Amazon.com Page
Getting Started with the Alexa Skills Kit
Free Video Training - An Introduction to Amazon Echo and the Alexa Skills Kit
Alexa Lighting API FAQ
Alexa Lighting API Developer Documentation
Alexa Connected Home Developer Forums

Want Amazon Developer blogs delivered to your inbox? Stay in the loop on the latest industry best practices, Amazon promotions, and new launches by subscribing to our weekly blog summary here.