Step 2: Configure Authorization URLs for Your App

In this step, you configure your skill to use app-to-app account linking and define the authorization URLs. You can use the Alexa developer console, Alexa Skills Kit Command Line Interface (ASK CLI), or the Account Linking Management REST API to configure account linking information. During this step, you specify your app's authorization URL (deep-link enabled), access token URL, client credentials, and scopes. For details, see URIs and endpoints.

In this topic, the terms URI and URL are used interchangeably.

Step 1:
Enable Deep Linking
→
Step 2:
Configure Authorization URLs
→
Step 3:
Handle the Authorization Request
→
Step 4:
Redirect to the Alexa app

Configure URLs in the Alexa developer console

For configuration details for your grant type, see Configure an Authorization Code Grant or Configure an Implicit Grant.

To enable app-to-app account linking in the developer console

  1. Sign in to the Alexa Skills Kit developer console.
  2. On the Skills tab, under SKILL NAME, scroll to find your skill.
  3. Under ACTIONS, expand the dropdown list in your skill's row, and then select Edit.
  4. On the menu, choose TOOLS, and then choose ACCOUNT LINKING.
  5. Turn on Allow users to authenticate using your mobile application.
  6. For the other settings, use the values described in Configure Account Linking.

Make sure that you follow these requirements when you add the authorization URLs:

  • The iOS and Android authorization URIs are the authorizationUrlsByPlatform described in Parameters for the authorization request to your app.
  • The app authorization URLs must comply with the specified URI syntax. The Alexa app opens this Universal Link or App Link URL to launch your app.
  • To enable app-to-app account linking, you must provide at least one of the URLs. In other words, you can enable one mobile platform without enabling the other. You can also use the same value for both URL fields.
  • For Android apps, Alexa also uses the Your Android App Authorization URI as the fallback authorization URI when the user doesn't have your app installed.
  • For iOS apps, Alexa also uses the Your Web Authorization URI as the fallback authorization URI when the user doesn't have your app installed.

Configure URLs with the CLI

Use the ASK CLI update-account-linking-info subcommand to configure app-to-app account linking.

The following example shows the JSON format for the accountLinkingRequest object. For more details, see Update account linking information REST API request body properties.

{
    "accountLinkingRequest": {
        "type": "AUTH_CODE",
        "authorizationUrl": "https://www.example.com/auth_url",
        "domains": ["www.example.com"],
        "clientId": "your.client.id.1",
        "scopes": [
            "scope_a",
            "scope_b"
        ],
        "accessTokenUrl": "https://www.example.com/accessToken_url",
        "accessTokenScheme": "HTTP_BASIC",
        "defaultTokenExpirationInSeconds": 20,
        "redirectUrls": [
            "https://www.example.com/redirect_url"
        ],
        "authorizationUrlsByPlatform": [{
                "platformType": "iOS",
                "platformAuthorizationUrl": "https://your.ios.url"
            },
            {
                "platformType": "Android",
                "platformAuthorizationUrl": "https://your.android.url"
            }
        ],
        "skipOnEnablement": true,
        "voiceForwardAccountLinking": "ENABLED",
        "pkceConfiguration": {
            "status": "ENABLED",
            "codeChallengeMethod": "S256"
        }
    }
}

Configure URLs with the REST API

Use the Account Linking Management REST API and the following settings for the accountLinkingRequest object to enable app-to-app account linking.

Field Description Type

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. For more details, see Let Users Enable Your Skill without Account Linking.

Boolean

type

Specifies the OAuth authorization grant type.

String

authorizationUrl

The URL of your authorization server, which must accept the user's credentials, authenticate the user, and generate an authorization code that the Alexa app can later pass to your authorization server to retrieve an access token that uniquely identifies the user with your service.

String

domains

A list of additional domains that your log-in page gets content from. You can specify up to 15 domains.

Array of String

clientId

Identifier that your log-in page uses to recognize that the request came from your skill.

String

scopes

Strings that indicate the access that you need for the user account, such as the user_id. Required for smart home skills. You can specify up to 15 scopes.

Array of String

accessTokenUrl

The URI for requesting authorization tokens. Required when type is AUTH_CODE.

String

clientSecret

A credential that you provide that lets the Alexa service authenticate with the Access Token URI. Alexa combines clientSecret with clientId to identify the request as coming from Alexa.

String

accessTokenScheme

Type of authentication used. Examples are HTTP_BASIC and REQUEST_BODY_CREDENTIALS.

String

defaultTokenExpirationInSeconds

Number of seconds that the access token is valid.

Integer

redirectUrls

List of URLs to redirect back to when the OAuth system initiates the linking process. Your authorization server calls this URI to take the user back to the Alexa app after the customer logs into your system.

Array of string

authorizationUrlsByPlatform

A list of authorization platform objects that contain the URL that 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 to open your app.

Array of authorization platforms

pkceConfiguration

Defines the Proof Key for Code Exchange (PKCE) parameters. Include if your authorization server supports PKCE using SHA-256.

The pkceConfiguration object contains two properties:

  • status – Indicates whether the authorization server supports PKCE.
    Valid values: ENABLED, DISABLED. Default: DISABLED.
  • codeChallengeMethod – Method used to create a code challenge. Account linking supports SHA-256.
    Valid value: S256.

Object

The following example shows a request to add app-to-app account linking authorization URLs. For a complete list of fields, see Update account linking information operation.

{
  "accountLinkingRequest": {
    "accessTokenScheme": "HTTP_BASIC",
    "accessTokenUrl": "https://api.amazon.com/auth/o2/token/",
    "authorizationUrl": "https://www.amazon.com/ap/oa/",
    "clientId": "yourSMAPIClientId",
    "clientSecret": "yourSMAPIClientSecret",
    "domains": [],
    "defaultTokenExpirationInSeconds": 20,
    "redirectUrls": [
        "https://www.example.com/redirect_url"
    ],
    "authorizationUrlsByPlatform": [
    {
        "platformType": "iOS",
        "platformAuthorizationUrl": "https://youriOSURL"
    },
    {
        "platformType": "Android",
        "platformAuthorizationUrl": "https://yourAndroidURL"
    }
    ],
    "scopes": ["profile"],
    "skipOnEnablement": true,
    "type": "AUTH_CODE",
    "pkceConfiguration": {
        "status": "ENABLED",
        "codeChallengeMethod": "S256"
    }
  }
}
Was this page helpful?

Last updated: frontmatter-missing