Validate and Use Access Tokens in Smart Home and Video Code
After a user successfully enables your smart home add-on or video skill and links their Alexa account with your device cloud, requests sent to your add-on or skill include the user's access token (token). Add logic to verify the token, then use the token to access information about the user's devices in your resource server.
Get the access token from the directive
When your add-on or 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 add-on 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 add-on 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
- Add Account Linking for Alexa
- Account Linking Concepts
- The OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth.com
Last updated: Jul 14, 2026
