App-to-App Account Linking (Starting From Your App)

The way you let users start account linking depends on the experience you want to create for your users. You can offer account linking to users in multiple places. For example, you can give users the option to enable account linking after they register your app or provide them with a button on a "Link to Alexa" page in your app's settings page. For the options you choose, make sure to explain the benefit of linking an account with Alexa.

To add an account linking button to your iOS app, do the following:

1. Open your Xcode IDE and open your storyboard.
2. Add a UIbutton to your view controller and name it something like "Link your account with Alexa". Consider using a name that indicates the benefit that the user gets by linking their account, such as "Listen to your music with Alexa", "Use Alexa to order a car with Ride Hailer".

   

3. On the top left of the Xcode IDE, click Show the assistant editor.
4. Create an action connection for your button by dragging the button to the code editor.

To add an account linking button to your Android app, do the following:

1. In Android Studio, in design mode, open the layout of the page that you want to add the app-to-app account linking button to.
2. From the palette of options, drag and drop a new button into your layout.

   

3. Define an ID for your button.

   

4. In the code for your page, initialize your app-to-app account linking button and define its onClick listener behavior to initiate the flow, as in the following example.

class AppToAppFragment : Fragment() {

  private lateinit var appToAppButton: Button
    
  override fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
    ): View? {
      val root = inflater.inflate(R.layout.appToAppPage, container, false)
      initComponents(root)

      appToApp.setOnClickListener {
        doAppToApp() 
      }
  }

  private fun initComponents(root: View) {
    appToAppButton = root.findViewById(R.id.appToAppAccountLinkingButton)
  }
}

For this step, see the following information:

• To enable Universal Links, follow the instructions from Apple at Enabling Universal Links.
• To enable Android App Links, follow the instructions from Android at Handling Android App Links.

Universal Links and App Links must comply with the specified URI syntax. Remember the domain and path that you added because you'll need them when you add redirect URLs to the skill details in the developer console.

For examples of enabling Universal Links, see the Apple documentation at Enabling Universal Links.

For examples of enabling App Links, see the Android documentation in Create Deep Links to App Content and in Verify App Links.

First, make sure that you base your skill on a skill type that supports account linking. Then, configure your skill for account linking by using the developer console, the ASK CLI, or Account Linking REST API as described in the examples. If you're just getting started with account linking, see Add Account Linking to Your Alexa Skill.

To enable app-to-app account linking using the developer console, take the following steps.

1. Sign in to the Alexa Skills Kit developer console.
2. Find your skill in the list. Under Actions for your skill, select Edit.
3. On the left side, click TOOLS, and then click ACCOUNT LINKING.
4. Turn on Allow users to link their account to your skill from within your application or website.
5. For the authorization grant type, select Auth Code Grant, if not already selected. App-to-app account linking supports authorization code grant only.
6. For the other settings, use the settings described in Configure Account Linking and heed the following additional requirements to fill in the redirect URLs:
   • For Your Redirect URLs, add the redirect URLs described in URLs and endpoints / Your app's redirect URLs. Alexa and LWA use these URLs to send the user back to your app.
   • The redirect URLs must comply with the specified URI syntax. The Alexa app opens this Universal Link or App Link URL to launch your app.
   • To handle different scenarios, you can add more than one redirect URL.
   • If your app doesn't support Universal Links or App Links, you should have a valid web page that your redirect URLs lead to. This should support the same process to receive the user's Amazon authorization code described in How it works.
   • Remember to add Your Redirect URLs for your iOS app, Android app, and website.

To enable app-to-app account linking using the ASK CLI, use the update-account-linking-info.

The following example shows the JSON format for the account-linking-request option. For more details about the fields, see Request body properties for Update account linking information REST API.

{
    "accountLinkingRequest": {
        "type": "AUTH_CODE",
        "authorizationUrl": "https://www.amazon.com/ap/oa/",
        "clientId": "your.skill.client.id.1",
        "scopes": [
            "user_id"
        ],
        "accessTokenUrl": "https://api.amazon.com/auth/o2/token",
        "accessTokenScheme": "HTTP_BASIC",
        "defaultTokenExpirationInSeconds": 20,
        "redirectUrls": [
            "https://www.example.com/your_apps.redirect_url"
        ],
        "authorizationUrlsByPlatform": [{
                "platformType": "iOS",
                "platformAuthorizationUrl": "https://your.ios.redirect_url"
            },
            {
                "platformType": "Android",
                "platformAuthorizationUrl": "https://your.android.redirect_url"
            }
        ],
        "skipOnEnablement": "true",
        "voiceForwardAccountLinking": "ENABLED"
    }
}

To enable app-to-app account linking by using the Account Linking Management REST API, use the following settings for the accountLinkingRequest structure.

The following is an example of a request to add redirect URLs by using the 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": "your.skill.client.id.1",
      "domains": [],
      "redirectUrls": ["yourRedirectURL1","yourRedirectURL2"],
      "scopes": ["user_id", "alexa::skills:account_linking"],
      "skipOnEnablement": true,
      "type": "AUTH_CODE",
      "pkceConfiguration": {
            "status": "ENABLED",
            "codeChallengeMethod": "S256"
      }
    }
}

You get the user's Amazon authorization code by either opening the Alexa app URL (for the Alexa app flow) or by making an HTTP GET request to the LWA authorization server (for the LWA flow). For iOS and Android, Amazon strongly encourages you to implement the Alexa app flow and use LWA only as a fallback.

To get the user's Amazon authorization code, you assemble an authorization request and then open the Alexa app URL (or the LWA fallback URL, if the Alexa app isn't installed) with the parameters described in URLs and endpoints. Include PKCE security if your app backend supports PKCE using SHA-256. If your backend doesn't fully support PKCE with SHA-256 or you're unsure, omit the PKCE parameters. Account linking supports the SHA-256 code challenge method only.

Amazon highly recommends that you assemble these URLs in your backend server and pass the assembled URLs to your app. That way, you can quickly change parameters, such as the stage, without rebuilding your app.

When the user acknowledges the linking request, the Alexa app redirects the user to your app's redirect URL, which is a parameter in the Alexa or LWA fallback URLs. The redirection includes the success or error parameters described next.

If the user's device can't launch your app by using the redirect URL that you provided, the user is redirected to that same redirect URL in their default browser. This might happen, for example, when:

• Universal Links or App Links aren't enabled in your app.
• Universal Links or App Links aren't enabled in your app for the redirect URLs that you provided.
• The version of the app on the user's device is an older version that doesn't support Universal Links or App Links.

In these cases, you should have a web page (at the same URL as the Universal Link or App Link) to receive the authorization code. When the user opens your web page, they might have to log in so that you can get the authorization code from your service.

For possible errors and the associated message to show the user, see Errors when obtaining the Amazon authorization code.

Success response of the HTTP GET request for the Alexa app URL

In the case of success, the response is a redirect URL that includes the user's Amazon authorization code and state. To handle this, see the Apple guidelines on Supporting Universal Links in Your App and Android guidelines in Handling Android App Links.

// Example success response from the Alexa app
https://yourRedirectURL?code={Amazon.Authorization.code}&state={your state}

// Example success response from LWA
https://yourRedirectURL?code={Amazon.Authorization.code}&scope={permission scope}&state={your state}

where:

• code: The Amazon authorization code that the Alexa app or LWA returns.
• state: The state that you passed in the authorization request. You should validate the state to avoid cross-site request forgery.
• scope: Permission scope. LWA returns alexa::skills:account_linking scope. The Alexa app doesn't return a scope parameter.
  

For additional details about OAuth2.0 authorization responses, see Authorization Response.

Error response of the HTTP GET request for the Alexa app URL

On error, the response is the redirect URL with the error and other parameters shown next. Your app must display the appropriate error message (an error page, UIAlertController, and so on). For the error message to display, see Errors when obtaining the Amazon authorization code.

// Example error response
HTTP 200
https://yourRedirectURL?error_description={Error description}&state={your state}&error={OAuth Error Code}

where:

• error: A single ASCII error code. Possible values: invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable.
• error_description: A description of the error.
  

For additional details about OAuth2.0 error responses, see Error Response.

In this example, the app gets both the Alexa app URL and the LWA fallback URL.

import Alamofire
import SwiftyJSON

class AlamofireHelper {

    // Your backend base URL from which you're requesting the URL
    static let BASE_URL = "https://exampleBackEndURL"
    
    /*! Get Alexa app Universal Link and LWA fallback URL
     @param userAccessToken for your backend server
     @param state maintained between client and server, caller should generate it 
     */
    static func getAlexaAppUrl(userAccessToken:String, state: String) -> DataRequest {
        let alexaAppUrl = "/alexaurl"
        let inputstate = "?state=" + state
        
        var urlRequest = URLRequest(url: URL(string: BASE_URL + alexaAppUrl + inputstate)!)
        urlRequest.addValue("Bearer " + userAccessToken, forHTTPHeaderField: "Authorization")
        return Alamofire.request(urlRequest)
    }
    
    private init() {}
}

// Call to your backend to get the authorization request URLs (Alexa app / LWA)
AlamofireHelper.getAlexaAppUrl(userAccessToken: savedSession.accessToken, state: StateHelper.generateState()).responseJSON {
    response in
    guard let status = response.response?.statusCode, 200..<300 ~= status else {
        self.createAlert(title: "Failed to get Alexa URL", message: "Failed to get Alexa URL")
        return
    }
    guard let responseValue = response.result.value else {
        self.createAlert(title: "Invalid response", message: "Invalid response")
        return
    }
    let reponseInJSON = JSON(responseValue)
    guard let companionApp = reponseInJSON["companionAppURL"].string,let lwaFallback = reponseInJSON["LWAFallBackURL"].string else {
        self.createAlert(title: "Error response", message: "Error response")
        return
    }
    guard let companionAppURL = URL(string: companionApp), let lwaFallbackURL = URL(string: lwaFallback) else {
        self.createAlert(title: "Incorrect URL format", message: "Incorrect URL format")
        return
    }
    // The openUniversalLinks code snippet can be found in another example
    self.openUniversalLinks(companionAppURL: companionAppURL, lwaFallbackURL: lwaFallbackURL)
}

In this example, the app opens the Alexa app URL or, the LWA fallback URL if the Alexa app isn't installed.

Note the following:

• This example uses the UIApplication.shared.open API to open the URL with the universalLinksOnly option.
• URLs only open when there is an app (in this case, the Alexa app) that's configured to handle Universal Links with the universalLinksOnly option. You can therefore pass closure expressions in completionHandler to handle the case in which the Alexa app doesn't launch (for example, the Alexa app wasn't installed or is a version that doesn't support Universal Links).
• If your app isn't able to launch the Alexa app when using the universalLinksOnly option, your app needs to get the Amazon authorization code by using LWA. For the LWA Fallback URL format, see URLs and endpoints. You can use SFAuthenticationSession on iOS 11 or ASWebAuthenticationSession on iOS 12.0 or higher. This gets the Safari user session and cookies, which avoids an extra login when the user is already logged in to Amazon.com on Safari. This will cause your app to display a window that asks the user's consent to share website information. iOS defines the content of the consent message.
• For iOS versions below 11.0, this example uses SFSafariViewController to send users to the LWA page. The SFSafariViewController doesn't ask for the user's consent to share website information; the Safari browser therefore doesn't share cookies with the SFSafariViewController.

import SafariServices

// Open the Alexa URL with option universalLinksOnly
// If it doesn't open the Universal Link, open the LWA fallback 
private func openUniversalLinks(companionAppURL: URL, lwaFallbackURL: URL) {
    UIApplication.shared.open(companionAppURL, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly:true]) {
        companionAppLaunched in
        if !companionAppLaunched {
            if #available(iOS 12.0, *) {
                WebSession.initWebAuthenticationSession(authURL: lwaFallbackURL)
            } else if #available(iOS 11.0, *) {
                WebSession.initAuthenticationSession(authURL: lwaFallbackURL)
            } else {
                let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
                self.present(safariViewController, animated: true, completion: nil)}
        }
    }
}

// Web session
class WebSession {
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    private static var authenticationSession: SFAuthenticationSession?
    
    @available(iOS 12.0, *)
    private static var webAuthenticationSession : ASWebAuthenticationSession?
    
    private static let CALLBACK_URL_SCHEME = "https://yourAppsUniversalLinkURL"
    
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    static func initAuthenticationSession(authURL:URL) {
        if let session = authenticationSession {
            session.cancel()
        }
        self.authenticationSession = SFAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            //Callback and error handling
        })
        self.authenticationSession?.start()
    }
    
    @available(iOS 12.0, *)
    static func initWebAuthenticationSession(authURL:URL) {
        if let session = webAuthenticationSession {
            session.cancel()
        }
        
        self.webAuthenticationSession = ASWebAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            // Callback and error handling
        })
        self.webAuthenticationSession?.start()
    }
    
    private init(){}
}

For websites, and as a fallback for when the Alexa app isn't installed on the iOS device, open the LWA URL. In this example, the app opens LWA in a view controller.

import SafariServices

// Open Login with Amazon in Safari View controller
private func openSafariView(lwaFallbackURL: URL) {
    let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
    self.present(safariViewController, animated: true, completion: nil)
}

In this example, the app validates and extracts the parameters from the call that the Alexa app made to its Universal Link.

// Handler for Universal Links in AppDelegate
// Add this method to handle incoming Universal Links
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL else {
            return false
    }
    let handlers : [UniversalLinkHandler] = [AuthResponseHandler(), ErrorResponseHandler()]
    var validatedResponse : ValidatedResponse?
    for handler in handlers {
        if handler.canHandle(incomingURL: incomingURL) {
            validatedResponse = handler.getValidatedResponse()
            let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "linkingStatusScreen") as! LinkingStatusViewController
            initialViewController.response = validatedResponse
            self.window?.rootViewController = initialViewController
            self.window?.makeKeyAndVisible()
            return true
        }
    }
    return false
}

// Incoming Universal Links handler protocol
protocol UniversalLinkHandler {

    //Validate the incoming URL scheme
    func canHandle(incomingURL:URL)-> Bool
    
    //Get the validated response
    func getValidatedResponse() -> ValidatedResponse?
}

extension UniversalLinkHandler {
    func validateState(state:String)->Bool {
        return StateHelper.validateState(state: state)
    }
}

// Successfully receiving the Amazon Authorization code
class AuthResponseHandler : UniversalLinkHandler {

    private let AUTH_RESPONSE_PARAMETERS: Set = ["code", "state", "scope"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
    
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            //duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            //Unrecognized parameters in URL
            if !AUTH_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let code = validatedParameters["code"], let state = validatedParameters["state"] else {
            return false
        }
        
        //validated the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = AuthResponse(url: incomingURL,code: code, state: state, scope: validatedParameters["scope"])
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Error authorization response handler
class ErrorResponseHandler : UniversalLinkHandler {
    private let ERROR_RESPONSE_PARAMETERS: Set = ["error", "error_description", "state"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        // Validate all query parameters 
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            // Duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            // Unrecognized parameters in URL
            if !ERROR_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let error = validatedParameters["error"], let errorDescription = validatedParameters["error_description"], let state = validatedParameters["state"] else {
            return false
        }
        
        // validate the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = ErrorResponse(url: incomingURL, error: error, errorDescription: errorDescription)
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Validated response
class ValidatedResponse {

    // Universal Link URL that launched the App
    private(set) var url: URL
    init (url: URL) {
        self.url = url
    }
}

// Amazon authorization code response per the OAuth2 specification 
class AuthResponse : ValidatedResponse{
    private(set) var code : String
    private(set) var state: String
    
    //scope will be returned in Login with Amazon, will not be present in Alexa Companion flow
    private(set) var scope: String?
    init(url:URL, code:String, state:String, scope: String?) {
        self.code = code
        self.state = state
        self.scope = scope
        super.init(url:url)
    }
}

// Error response per the OAuth2 specification 
class ErrorResponse : ValidatedResponse {
    private(set) var error : String
    private(set) var errorDescription: String
    init(url: URL, error:String, errorDescription:String) {
        self.error = error
        self.errorDescription = errorDescription
        super.init(url: url)
    }
}

Make a request to your backend service to get both the Alexa app URL and the LWA fallback URL. You can implement this request in any way that you prefer, such as using RetroFit or any other Android library. The following code is a simple example.

fun doAppToApp(){
  val appToAppUrls: AppToAppUrls = yourBackendService.getAppToAppUrls();
    
  // This function is shown in a different example 
  openAlexaAppToAppUrl(appToAppUrls.alexaAppUrl, appToAppUrls.lwaFallBackUrl)
}

data class AppToAppUrls(
  @SerializedName("alexaAppUrl")
  val alexaAppUrl: String,

  @SerializedName("lwaFallBackUrl")
  val lwaFallBackUrl : String
)

interface BackendService {
  fun getAppToAppUrls() : AppToAppUrls
}

In this example, the app opens the Alexa app URL or, if the Alexa app is not installed, the LWA fallback URL.

Note the following:

• This example uses the PackageManager to verify that the Alexa app is installed and to verify that the installed version of the Alexa app can handle app-to-app account linking.
• If the Alexa app isn't installed or can't handle app-to-app account linking, your app must get the Amazon authorization code by using the LWA flow. For the LWA fallback URL format, see URLs and endpoints.
• This example opens the URLs by using the Android ACTION_VIEW intent. The app-to-app URL will open in the Alexa app and the LWA fallback URL will open in the user's default browser.

private fun openAlexaAppToAppUrl(alexaAppUrl: String, lwaFallbackUrl: String){

    if (AlexaAppUtil.isAlexaAppSupportAppLink(fragmentContext!!)) {
        val alexaAppToAppIntent = getAppToAppIntent(alexaAppUrl);
        startActivity(alexaAppToAppIntent)
    } else {
        val lwaAppToAppIntent = getAppToAppIntent(lwaFallbackUrl);
        startActivity(lwaAppToAppIntent)
    }
}

private fun getAppToAppIntent(appToAppUrl: String): Intent {
    return Intent(Intent.ACTION_VIEW, Uri.parse(appToAppUrl))
}
/**
 * Utility to check if the Alexa app is installed and supports app-to-app.
 */
object AlexaAppUtil {
    
    private const val ALEXA_PACKAGE_NAME = "com.amazon.dee.app"
    private const val ALEXA_APP_TARGET_ACTIVITY_NAME = "com.amazon.dee.app.ui.main.MainActivity"
    
    private const val REQUIRED_MINIMUM_VERSION_CODE = 866607211 

    /**
     * Check if the Alexa app is installed and supports App Links.
     *
     * @param context Application context.
     */
    @JvmStatic
    fun doesAlexaAppSupportAppToApp(context: Context): Boolean {
        try {
            val packageManager: PackageManager = context.packageManager
            val packageInfo = packageManager.getPackageInfo(ALEXA_PACKAGE_NAME, 0)

            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
                packageInfo.longVersionCode > REQUIRED_MINIMUM_VERSION_CODE
            } else {
                packageInfo != null
            }

        } catch (e: PackageManager.NameNotFoundException) {
            // The Alexa App is not installed
            return false
        }
    }
}

In this example, the app validates and extracts the parameters from the call that the Alexa app made to its App Link.

/**
 * App-to-app result page landing activity.
 */
class AppToAppResultPageActivity : AppCompatActivity() {
  private lateinit var statusText: TextView
  private lateinit var goBackButton: Button

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val appLinkData = intent.data

    setContentView(R.layout.app_to_app_result)
    initializeComponents()
    statusText.text = "Linking your account"

    // Send the data returned from the Alexa App / LWA to your backend
    // to call the Skill Enablement API to link the accounts
    val accountLinking = linkAccountInBackend(appLinkData)

    displayAccountLinkingStatus(result);
  }

  private fun initializeComponents() {
    statusText = findViewById(R.id.text_status)
    goBackButton = findViewById(R.id.btn_goback)
    goBackButton.setOnClickListener {
      val intent = Intent(this, MainActivity::class.java)
      startActivity(intent)
    }
  }
}

In this example, the app generates and validates the state between the request and the response. You must validate incoming requests by using the state to prevent cross-site request forgery.

import Foundation
import Security

class StateHelper {
    private static let STATE_VALID_FOR = 3600
    // Base64 (iOS + TimeStamp + Secure Random UUID)
    private static let NUMBER_OF_PARAMETER = 3
    
    static func generateState(session: Session)-> String {
        var buffer = Data(count: 30)
        let _ = buffer.withUnsafeMutableBytes {
            SecRandomCopyBytes(kSecRandomDefault, 30, $0)
        }
        let state = ("iOS." + String(Int64(Date().timeIntervalSince1970)) + "." + buffer.base64EncodedString()).encodeToURISafeBase64()
        
        // store state in session manager for future validation
        session.state = state
        LocalSessionManager.saveSession(session: session)
        
        return state
    }
    
    static func validateState(state: String) -> Bool {
        guard let originalState = LocalSessionManager.loadSession()?.state  else {
            return false
        }
        if state != originalState {
            return false
        }
        if let timeStampString = originalState.decodeFromURISafeBase64()?.split(separator: "."), timeStampString.count == NUMBER_OF_PARAMETER, let timeStamp = Int64(timeStampString[1]){
            if Int64(Date().timeIntervalSince1970) - timeStamp <= STATE_VALID_FOR {
                return true
            }
        }
        if let session = LocalSessionManager.loadSession() {
            session.state = nil
            LocalSessionManager.saveSession(session: session)
        }
        return false
    }
    
    private init() {}
}

extension String {
    func decodeFromURISafeBase64() -> String? {
        let base64String = String(self.map {
            // replace unsafe characters 
            character in
            if character == "." {
                return  "+"
            } else if character == "_" {
                return "/"
            } else if character == "-" {
                return "="
            }
            return character
        })
        guard let data = Data(base64Encoded: base64String) else {
            return nil
        }
        return String(data: data, encoding: .utf8)
    }
    
    func encodeToURISafeBase64() -> String {
        return String(Data(self.utf8).base64EncodedString().map{
            // replace back unsafe characters 
            character in
            if character == "+" {
                return  "."
            } else if character == "/" {
                return "_"
            } else if character == "=" {
                return "-"
            }
            return character
        })
    }
}

Call the LWA Get access token with authorization code operation with the following request parameters. If your app backend supports PKCE, include the code_verifier parameter. For possible errors and the associated message to show the user, see Errors when exchanging the Amazon authorization code for an Amazon access token.

Request

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code
&code=Amazon.Authorization.code
&client_id=yourClientId
&client_secret=yourClientSecret
&code_verifier=AB12CVEXAMPLE
&redirect_uri=yourRedirectUri

Response

HTTP 200
Content-Type: application/json
{
  "access_token": "AmazonAccessToken",
  "expires_in": "3600",
  "refresh_token": "YourRefreshToken",
  "token_type": "bearer"
}

For more details about getting access tokens from LWA, see the following references:

• Access Token Request
• Access Token Response
• Access Token Errors

In this example, the app exchanges the user's Amazon authorization code for an Amazon access token.

const axios = require('axios');

// Amazon OAuth token request in the backend
const OAuthRequests = (function () {
    const header = {
        "headers": {
            "Content-Type": "application/json"
        }
    };

    const accessTokenBody = function (amazonAuthCode, state) {
        return {
            "grant_type": "authorization_code",
            "code": amazonAuthCode,
            "redirect_uri": config.skillConfig.redirect_uri,
            "client_id": config.skillConfig.client_id,
            "client_secret": config.skillConfig.client_secret,
            "code_verifier": config.skillConfig.code_verifier
        };
    };

    return {
        accessTokenRequest: (authcode, state) => {
            return {
                header: header,
                body: accessTokenBody(authcode, state)
            }
        }
    }
})();

// Request the Amazon access/refresh tokens from the Amazon OAuth token server
function getAccessTokenByAuthcode(amazonAuthCode, state) {
    const accessTokenRequest = OAuthRequests.accessTokenRequest(amazonAuthCode, state);
    return axios.post(config.endpoints.oauthEndpoint, accessTokenRequest.body, accessTokenRequest.header);
}

Make a request to the Alexa Skill Enablement API by using the following URL format: [BASE URL]/v1/users/~current/skills/{yourSkillId}/enablement, where [BASE URL] depends on the region where your user is located: https://api.amazonalexa.com, https://api.eu.amazonalexa.com orhttps://api.fe.amazonalexa.com.

The security provider that you use must authorize calls from the app to the app's backend server and provide a server-side API to get the authorization code for the user who is currently logged in to your app. (That is, it needs to provide the authorization code for the user's account in your service.) Alexa will exchange this code for your user's access token to access the user's resources.

For possible errors and the associated message to show the user, see Alexa Skill Enablement API.

To enable the skill, make the following request:

Request
In the request shown next, set HOST to one of the following, depending on the user's region: api.amazonalexa.com, api.eu.amazonalexa.com, or api.fe.amazonalexa.com

POST /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: api.amazonalexa.com, api.eu.amazonalexa.com, api.fe.amazonalexa.com
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"
{
    "stage": "skill stage",
    "accountLinkRequest": {
      "redirectUri": "https://yourRedirectURI",
      "authCode": "Your user's authorization code from your authorization server",
      "type": "AUTH_CODE"
    }
}

Success response

HTTP 201
Content-Type: application/json
{
  "skill": {
    "stage": "your skill stage",
    "id": "your skill id"
  },
  "user": {
    "id": "User ID"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLED"
}

Note that you can disable the skill and unlink the account for the user by making a Disable skill and unlink account request to the Alexa Skill Enablement API.

In this example, the app enables the skill and completes account linking.

const _ = require('lodash');
const axios = require('axios');
const {config} = require('../config/skillconfig');
const {getAccessTokenByAuthcode} = require('./oauthrequests');

// Request to the Alexa Skill Enablement API in the backend
const AlexaServiceRequest = (() => {
    const header = (amazonAccessToken) => {
        return {
            "headers": {
                "Content-Type": "application/json",
                "Authorization": "Bearer " + amazonAccessToken
            }
        };
    };

    const body = (userAuthCode) => {
        return {
            "stage": config.skillConfig.stage,
            "accountLinkRequest": {
                "redirectUri": config.skillConfig.redirect_uri,
                "authCode": userAuthCode,
                "type": "AUTH_CODE"
            }
        }
    }

    return {
        createEnablement: (amazonAccessToken, userAuthCode) => {
            return {
                header: header(amazonAccessToken),
                body: body(userAuthCode)
            }
        }
    }
})();

function createEnablementWithAccountLink(amazonAuthCode, userAuthcode, state) {

    // Exchange Amazon OAuth Code for Amazon Access Token
    const tokenPromise = getAccessTokenByAuthcode(amazonAuthCode, state);
    return tokenPromise.then((res) => {
        if (!_.has(res, 'data.access_token')) {
            throw Error("Amazon AccessToken is invalid");
        }
        console.log(res);
        const amazonAccessToken = res.data.access_token;

        // Call the Alexa Skill Enablement API to create enablement
        const createEnablementRequest = AlexaServiceRequest.createEnablement(amazonAccessToken, userAuthcode);
        return sendPostRequests(config.endpoints.alexaServiceEndpoints, createEnablementRequest.body, createEnablementRequest.header);
    });
}

// Post enablement to the Alexa Skill Enablement API
function sendPostRequests(endpoints, body, header) {
    var alexaServicePromises = []

    // Post for each Alexa Skill Enablement API regional endpoint for the user
    endpoints.forEach((endpoint)=> {
        alexaServicePromises.push(axios.post(endpoint, body, header));
    });
    return new Promise((resolve, reject)=> {
        var failures = 0;
        alexaServicePromises.forEach((promise)=> {
            promise.then((res)=> {
                if (res.status == 201) {
                    resolve(res.data);
                } else {
                    if (++failures == alexaServicePromises.length) {
                        reject(res.data);
                    }
                }
            }).catch((err)=> {
                if (++failures == alexaServicePromises.length) {
                    reject(err.data);
                }
            })
        })
    });
}

You can use different UI components — for example, a table or page view — to show the account linking status.

In this example, the app displays the account linking status using a UIViewController.

1. In your Xcode IDE, go to the main storyboard to add a new view controller. The storyboard ID for this view controller is "linkingStatusScreen".
2. Add a new Cocoa Touch class file, select a subclass of UIViewController, and connect your class file with the UIViewController in identity inspector.
3. Add a header, a status UILabel to show the account linking status, a UIButton to close this page, and a UIActivityIndicatorView to show the loading animation while your app is calling the Alexa service.

import UIKit

class LinkingStatusViewController: UIViewController {
    
    @IBOutlet weak var header: UILabel!
    @IBOutlet weak var status: UILabel!
    @IBOutlet weak var closeButton: UIButton!
    @IBOutlet weak var indicator: UIActivityIndicatorView!
    
    var response : ValidatedResponse?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        if let res = self.response {
            passValidatedResponse(validatedResponse: res)
        }
    }
    
    private func updateView(header:String, status:String, animating: Bool,closeButton:Bool) {
        if animating {
            self.indicator?.startAnimating()
        } else {
            self.indicator?.stopAnimating()
        }
        self.indicator?.isHidden = !animating
        self.header?.text = header
        self.status?.text = status
        
        self.closeButton.isEnabled = closeButton
        if closeButton {
            self.closeButton.backgroundColor = #colorLiteral(red: 0.1960784314, green: 0.6039215686, blue: 0.8392156863, alpha: 1)
        } else {
            self.closeButton.backgroundColor = #colorLiteral(red: 0.6000000238, green: 0.6000000238, blue: 0.6000000238, alpha: 1)
        }
    }
}

extension LinkingStatusViewController {
    func passValidatedResponse(validatedResponse: ValidatedResponse) {
        if validatedResponse is AuthResponse {
            let response: AuthResponse = validatedResponse as! AuthResponse;
            updateView(header: "Status", status: "Loading", animating: true, closeButton: false)
            usingAuthCodeToGetAccessToken(amazonAuthCode: response.code)
        } else if (validatedResponse is ErrorResponse) {
            let response: ErrorResponse = validatedResponse as! ErrorResponse;
            updateView(header: response.error, status: response.errorDescription, animating: false, closeButton: true)
        } else {
            updateView(header: "Unknown request", status: validatedResponse.url.absoluteString, animating: false, closeButton: true)
        }
    }
    
    // Complete account linking
    private func usingAuthCodeToGetAccessToken(amazonAuthCode: String) {
        guard let session = LocalSessionManager.loadSession(), session.sessionValid  else {
            updateView(header: "Status", status: "User not login", animating: false, closeButton: true)
            return;
        }
        AlamofireHelper.completeAccountLinking(userAccessToken: LocalSessionManager.loadSession()!.accessToken, amazonAuthCode: amazonAuthCode, state: StateHelper.generateState(session: session)).responseJSON(queue: DispatchQueue.global(qos: .userInitiated), options: []) {
            response in
            if let status = response.response?.statusCode, 200..<300 ~= status {
                DispatchQueue.main.sync {
                    self.updateView(header: "Status", status: "Account Linking Succeed", animating: false, closeButton: true)
                }
                return
            } else {
                DispatchQueue.main.sync {
                    self.updateView(header: "Failed", status: "Account Linking failed", animating: false, closeButton: true)
                }
            }
        }
    }
}

// Open the account linking status page
let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "linkingStatusScreen") as! LinkingStatusViewController
initialViewController.response = validatedResponseself.window?.rootViewController = initialViewController
self.window?.makeKeyAndVisible()

For details about how to validate and use the access token, see the skill type:

• Validate and Use Access Tokens in Custom Skill Code
• Validate and Use Access Tokens in Smart Home, Video, and Meetings Skill Code
• Validate and Use Access Tokens in Music Skill Code