Account Linking Schemas, v0

Account Linking Schemas

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

You can create and get account linking information by using the create-account-linking and get-account-linking subcommands of the ask smapi command.

See also: Alexa Skills Kit Command Line Interface (ASK CLI) Overview

Account Linking Request

Following is the JSON format for account linking information:

{
  "accountLinkingRequest": {
    "type": "AUTH_CODE",
    "authorizationUrl": "string",
    "domains": [
      "string"
    ],
    "clientId": "string",
    "scopes": [
      "string"
    ],
    "accessTokenUrl": "string",
    "clientSecret": "string",
    "accessTokenScheme": "HTTP_BASIC",
    "defaultTokenExpirationInSeconds": integer
  }
}

accountLinkingRequest Object

Field Description Type
type Specifies the OAuth authorization grant type. Use AUTH_CODE or IMPLICIT. NOTE: You must use AUTH_CODE with smart home skills. string
authorizationUrl Authorization URI string
domains A list of additional domains that your login page fetches content from. You can specify up to 15 domains. string array
clientId Identifier your login page uses to recognize that the request came from your skill. string
scopes Indicates the access that you need for the customer account such as user_id. This field is required for smart home skills. You can specify up to 15 scopes. string array
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
accessTokenScheme The type of authentication used such as HTTP_BASIC, or REQUEST_BODY_CREDENTIALS. Required only when AUTH_CODE is specified. string
defaultTokenExpirationInSeconds Optional. The time in seconds for which access token is valid. If the OAuth client returns "expires_in", it will be overwritten by this parameter. Only applicable if type is AUTH_CODE. integer

Redirect URLs After Customer Account Authenticated

As described in Redirect URL Values, the redirect URL is the URL to which your service redirects the customer after the customer has been authenticated. This redirect URL is referenced with the redirect_uri field.

Because the redirect_uri field has constant, pre-determined values, it is not part of the account linking schema, and thus cannot be parsed from user input.

For an authorization code grant, such as used for all smart home skills and some custom skills, the format of the redirect_uri value is as follows:

{baseUrl}/api/skill/link/{vendorId}

For an implicit grant, which is used for some custom skills, the format of the redirect_uri value is as follows:

{baseURL}/spa/skill/account-linking-status.html?vendorId={vendorId}

The list of valid HTTPS redirection endpoints, which are possible values for baseUrl, include the following:

  • "https://pitangui.amazon.com"

  • "https://layla.amazon.com"

See How Account Linking Works for more information on the difference between these OAuth authorization grant types.

Was this page helpful?

Last updated: Nov 29, 2023