Authenticate an Alexa User to a User in Your System with Account Linking

This page moved to ../account-linking/account-linking-for-sh-and-other.html.

A customer provides the credentials that authenticate them in your system as a part of the skill-enabling process. This is called account linking, and it is required when a customer enables a smart home skill. As a result, when Alexa sends your skill a directive, it includes these customer credentials as a bearer token in the scope section of the directive. You can then use this token to validate the user with your system.


Your device cloud must have OAuth 2.0 enabled and support the authorization code grant flow type. If you have not implemented OAuth 2.0, you can use Login with Amazon (LWA) as your OAuth 2.0 provider or any provider that has a certificate signed by an Amazon-approved certificate authority. The Amazon-approved certificate authorities includes the certificate list here with the exception of

In addition, access tokens provided by your system must have a lifetime of at least 6 minutes. This means the expires_in parameter of your access token response must be greater or equal to 360 .

Provide account linking info

You provide account linking information such as account credentials, token URIs and privacy policy information on the Build page of the developer console.

Edit your skill and select Account Linking from the sidebar, then fill in the fields as described below.

Field Description
Authorization URI The URL for your OAuth implementation/server that points to a login dialog or page.
Client ID The identifier the login page uses to recognize the request came from your skill. This is specified by the OAuth provider and is passed to the authorization URL as the client_id parameter.
Scope Required to identify the kind of account access or permission level your skill requires. These values are determined by your OAuth provider/implementation and you should consult their documentation to know what scopes to specify.
Redirect URLs Once a user logs in, this is the page that they will be redirected to by the OAuth provider. You must white-list these URLs with your OAuth provider. The terminology to configure these may vary depending on your OAuth provider. For example, for Login with Amazon, you configure these as Allowed Return URLs.
Authorization Grant Type: Auth Code Grant This option is preselected for smart home skills because this is the supported authorization flow.
Access Token URI The URL for the OAuth server/provider that provides the access and refresh tokens, and responds to token requests and token refresh requests.
Client Secret This is provided by the OAuth provider and is combined with the Client ID to authenticate the request is from your skill.
Client Authentication Scheme Optionally identifies the type of authentication Alexa should provide when requesting tokens from the Access Token URI.

Getting the authentication information

When you receive a directive from Alexa, it will include 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": {}

You should extract this token and use it to authenticate the user in your system.