Validate and Use Access Tokens in Smart Home, Video, and Meetings Skill Code
Once a user successfully enables your smart home, video, or meetings skill and links their Alexa account with your device cloud, requests sent to your skill include the user's access token (token
). Add logic to the service for your skill to verify the token, then use it to access information about the user's devices in the resource server.
Get the access token from the directive
When your skill receives a directive from Alexa, it includes an endpoint
section that contains a scope
. The scope contains a bearer token that you can use to authenticate the user in your system.
Following is an example endpoint that contains a bearer token:
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
Retrieve the token from endpoint.scope.token
.
Verify that the token is valid
After you have the token
, verify that the token identifies a user in your resource server. The token could become invalid for multiple reasons, for example:
-
The user deleted or canceled their account with your service. For example, an Alexa user might have set up account linking with My Lights, and then later canceled their My Lights account. At this point, the token stored by the Alexa service would identify a non-existent user.
-
The token has expired, and the Alexa service was unable to obtain a new token. This can occur with an authorization code grant if your authorization server does not provide refresh tokens.
If the token is valid, handle the request normally. You can use the token to access data from your resource server as needed. In the My Lights example, the skill would access the device cloud and take an appropriate action based on the directive the user requested. For example, if the user invoked the TurnOn
directive, the skill would connect with the device cloud to turn on a light.
Respond to the user if the token is invalid or expired
If the access token is invalid, return an ErrorResponse
with the type
set to one of the following:
EXPIRED_AUTHORIZATION_CREDENTIAL
(for an expired token)INVALID_AUTHORIZATION_CREDENTIAL
(for an invalid token)
EXPIRED_AUTHORIZATION_CREDENTIAL
or INVALID_AUTHORIZATION_CREDENTIAL
error codes for any other error reason. Sending these error codes triggers deletion of the customer's account linking tokens, thereby unlinking their account with your service from the Alexa side. The only recourse for customers in this scenario is to re-link their accounts.Related topics
- Quick Reference: Add Account Linking to an Alexa Skill
- Add Account Linking to Your Alexa Skill
- Account Linking Concepts for Alexa Skills
- The OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth.com
Last updated: Sep 10, 2024