Account Linking Schemas

Note: Sign in to the developer console to build or publish your skill.

The accountLinkingRequest structure is a JSON representation of the account linking information shown on the Build > Account Linking section of the developer console.

To create and get account linking information, you can use the update-account-linking-info and get-account-linking-info subcommands of the ASK CLI.

Account linking request

Field	Description	Type
`accessTokenScheme`	The type of authentication used such as `HTTP_BASIC`, or `REQUEST_BODY_CREDENTIALS`. Required only when `AUTH_CODE` is specified.	String
`accessTokenUrl`	URI for requesting authorization tokens. Required only when `AUTH_CODE` is specified for `type`.	String
`clientSecret`	A credential you provide that lets the Alexa service authenticate with the Access Token URI. This is combined with `clientId` to identify the request as coming from Alexa.	String
`defaultTokenExpirationInSeconds`	Optional. The time in seconds for which the access token is valid. This value is used if the OAuth client does not return `expires_in`. If the OAuth client returns `expires_in`, the value provided by the OAuth client is used instead. Only applicable if `type` is `AUTH_CODE`.	Integer
`domains`	A list of additional domains that your login page fetches content from. You can specify up to 15 domains.	Array of String
`reciprocalAccessTokenUrl`	Optional. Link(s) that send the user back to your app after they acknowledge the linking request in the Alexa app or Login with Amazon using app-to-app account linking. In the developer console, you specify these on the Build > Account Linking page using the Your Redirect URLs field.	This URI will be invoked with authorization codes that can be exchanged for Alexa access tokens.
`redirectUrls`	Something	Array of String
`scopes`	Indicates the access that you need for the user account such as `user_id.` This field is required for smart home skills. You can specify up to 15 scopes.	Array of String
`skipOnEnablement`	Set to `true` to let users enable the skill without starting the account linking flow. Set to `false` to require the normal account linking flow when users enable the skill. See Let Users Enable Your Skill without Account Linking.	Boolean
`type`	Specifies the OAuth authorization grant type. Use `AUTH_CODE` or `IMPLICIT`. NOTE: You must use `AUTH_CODE` with smart home skills.	String
`voiceForwardAccountLinking`	Optional. Specifies whether the skill supports voice-forward account linking. Valid values: `ENABLED` or `DISABLED`. Default value is `DISABLED`. To enable your skill to use voice-forward account linking, use the Update account linking information API to set the `voiceForwardAccountLinking` field to `ENABLED`.	String enum
`authorizationUrlsByPlatform`	A list of authorization platform objects that contain the URL that will be used as a Universal Link or App Link to open the authorization page of your app. An authorization platform object contains two properties: `platformType` – The mobile platform your app should use for app-to-app account linking. Valid values: `iOS` or `Android`. `platformAuthorizationUrl` – The HTTPS Universal Link or App Link that will be used to open your app. For details, see App-to-App Account Linking (Starting From the Alexa App).	Array of authorization platforms

Sample account linking request

{
  "accountLinkingRequest": {
    "skipOnEnablement": "true",
    "type": "AUTH_CODE",
    "authorizationUrl": "string",
    "domains": [
      "string"
    ],
    "clientId": "string",
    "scopes": [
      "string"
    ],
    "voiceForwardAccountLinking": "string",
    "accessTokenUrl": "string",
    "reciprocalAccessTokenUrl": "string",
    "clientSecret": "string",
    "accessTokenScheme": "HTTP_BASIC",
    "defaultTokenExpirationInSeconds": 3600,
    "redirectUrls": [
      "string"
    ],
    "authorizationUrlsByPlatform": [
     {
       "platformType": "iOS",
       "platformAuthorizationUrl": "https://youriOSURL"
     },
     {
       "platformType": "Android",
       "platformAuthorizationUrl": "https://yourAndroidURL"
     }
    ]    
  }
}

Redirect URLs

In terms of account linking, there are two types of redirect URLs: Alexa redirect URLs and your redirect URLs. The difference is as follows:

Alexa redirect URLs – These URLs, which point to the Alexa app, have constant, predetermined values. You do not define them, which is why they are not in the account linking request schema defined in the previous section. You can find these URLs in the developer console on the Build > Account Linking page in the Alexa Redirect URLs field. When the Alexa app makes a request to your authorization URI, it passes the Alexa redirect URLs using the redirect_uri field in the query parameters.

For authorization code grants, the redirect_uri format is {baseUrl}/api/skill/link/{vendorId}.

For implicit grants, the redirect_uri format is {baseURL}/spa/skill/account-linking-status.html?vendorId={vendorId}. Valid values for baseUrl are https://pitangui.amazon.com, https://layla.amazon.com, and https://alexa.amazon.co.jp.
Your redirect URLs – These URLs, which point to your own app, are only for app-to-app account linking implementations. You specify these URLs in the developer console on the Build > Account Linking page using the Your Redirect URLs field or, if you are using SMAPI, the redirectUrls field of the account linking request schema defined in the previous section.

Last updated: Jun 13, 2022