article

Many issues that arise when trying to implement App-to-App Account Linking (Starting From Your App) and enabling the Skill Activation API can be resolved by testing and troubleshooting. This article will cover issues with knowing which client IDs, secrets and scopes to use when calling the Skill Activation API.

For troubleshooting account linking issues from the Alexa app, check out the Alexa Account Linking Debugging Tips guide.

For best practices, check out the Best Practices to Successfully Implement App-to-App Account Linking (Starting From Your App) in Your Skill blog.

Knowing the different security profiles

There are two different security profiles with client IDs and client secrets used for app-to-app account linking and the Skill Activation API. Many issues can be resolved by understanding which client ID and secret to use for exchanging authorization codes and access tokens. Check out the descriptions below:

• Security profile A: Your Client ID and Your Secret associated with the authorization server that you manually input in the account linking section of the skill
• 
  
  • This is the client ID and secret that you use with other scopes defined in the account linking section of the skill (such as profile) to retrieve an authorization code from your authorization server to be used later
  • If using LWA, the client ID and secret is generated when a new security profile is created on the Amazon Developer Console
• Security profile B: Alexa Client Id and Alexa Client Secret from the Alexa developer console when the skill opts in to app-to-app account linking
• 
  
  • This is unique to each skill and cannot be edited, only copied from the Alexa developer console
  • This is the client ID and secret that you use with the “alexa::skills::account_linking” scope to first retrieve an authorization code from the LWA API, then exchange that auth code retrieve an access token to be used later

Debugging issues with retrieving access tokens, auth codes and Skill Activation API

In order to call the Skill Activation API, there are three key steps:

a) Retrieve an access token from Amazon using Security profile B

b) Retrieve an authorization code from the skill's authorization server using Security profile A

c) Call the Skill Activation API with the access token and authorization code from the previous two steps

Most issues regarding these steps stem from using the wrong client ID, secret, scope and grant_type. Check out each section below for specifics:

1. Failing to retrieve the user’s Amazon auth code

If failing to retrieve the user's Amazon auth code:

• You should be using the client ID and secret from Security profile B (Alexa Client Id and Alexa Client Secret)
• You should be using the alexa::skills::account_linking scope here to retrieve the auth code - this will be used by your app to exchange it for an Amazon access token
• List of error messages when failing to retrieve the Amazon auth code

2. Failing to exchange the user’s auth code for an access token

If failing to exchange the Amazon auth code for an Amazon access token:

• You should be using the client ID and secret from Security profile B (Alexa Client Id and Alexa Client Secret)
• Check the grant_type is set to authorization_code
• Use the auth code taken from step 1 above
• List of error messages when failing to exchange the auth code

3. Enabling the skill with the Skill Activation API

If failing to enable the skill using the Alexa Skill Activation API:

• Make sure you're using the access token they retrieved using the scope alexa::skills::account_linking as per step 2 above
• Make sure you're using the client ID and secret from Security profile A (Your Client ID and Your Secret) when retrieving the access token to use as in the Bearer {Amazon Access Token}
• Make sure you're using a new auth code generated by your authorization server for the authCode parameter in the accountLinkRequest object, not an auth code that has already been used anywhere in this process - once an auth code is used, it can no longer be used again to retrieve access tokens
• List of error messages when failing to enable the skill using the Skill Activation API

If you are using LWA for authentication while also using App-to-App account linking

• When using LWA, customers will be required to log in twice - this is a limitation right now and cannot be avoided for third party authentication servers that require another login. This is the same for any third party service that requires a login to generate an auth code, so that keep that in mind.
• Use Security profile B (Alexa Client Id and Alexa Client Secret) to call the LWA fallback URL and retrieve the following:
  • An authorization code for the authCode parameter in the accountLinkRequest object
  • An access token used in the Authorization header
• Use Security profile A (Your Client ID and Your Secret) when actually calling the Skill Acitvation API, which is the same security profile created from the Amazon Developer Console
• Note: the scope when calling the Skill Activation API should not be alexa::skills:account_linking - use any scope that you have defined within the Scope field (such as profile per the screenshot above)
• Do not reuse the auth code for the authCode parameter in the accountLinkRequest object that you used to exchange for an Amazon access token - you will need a fresh auth code from LWA to use in the accountLinkRequest object
• Check out more tips for LWA on the documentation here under the “How to do it” section