Account Linking Management

This document describes all API operations related to linking Alexa user accounts to other OAuth identity providers. The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

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

Get account linking information

Request

GET /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. Accepted values are development and live (case sensitive). Path Yes

Response

HTTP/1.1 200 OK

Headers

ETag: <etag_value>

Body

See Account Linking Schemas.

{
  "accountLinkingResponse": {
    "skipOnEnablement": "true",
    "clientId": "abc",
    "authorizationUrl": "https://www.example.com/auth_url",
    "accessTokenUrl": "https://www.example.com/accessToken_url",
    "domains": [
      "www.example.com"
    ],
    "scopes": [
      "scope_a",
      "scope_b"
    ],
    "accessTokenScheme": "HTTP_BASIC",
    "type": "AUTH_CODE",
    "voiceForwardAccountLinking": "ENABLED",    
    "defaultTokenExpirationInSeconds": 20,
    "redirectUrls": [
      "https://www.example.com/redirect_url"
    ],
    "authorizationUrlsByPlatform": [
     {
       "platformType": "iOS",
       "platformAuthorizationUrl": "https://youriOSURL"
     },
     {
       "platformType": "Android",
       "platformAuthorizationUrl": "https://yourAndroidURL"
     }
    ]        
  }
}

Exceptions

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Update account linking information

Request

PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill Path Yes
stage Stage of the skill. Accepted value is development (case sensitive). Path Yes

Headers

If-Match: <etag_value>

Body

Contains an accountLinkingRequest object. See Account Linking Schemas.

{
  "accountLinkingRequest": {
    "skipOnEnablement": "true",
    "type": "AUTH_CODE",
    "authorizationUrl": "https://www.example.com/auth_url",
    "domains": [
      "string"
    ],
    "clientId": "string",
    "scopes": [
      "www.example.com"
    ],
    "voiceForwardAccountLinking": "ENABLED",
    "accessTokenUrl": "https://www.example.com/accessToken_url",
    "clientSecret": "abcdaslkaa",
    "accessTokenScheme": "HTTP_BASIC",
    "defaultTokenExpirationInSeconds": 20,
    "redirectUrls": [
      "string"
    ],
    "authorizationUrlsByPlatform": [
     {
       "platformType": "iOS",
       "platformAuthorizationUrl": "https://youriOSURL"
     },
     {
       "platformType": "Android",
       "platformAuthorizationUrl": "https://yourAndroidURL"
     }
    ]           
  }
}

Response

HTTP/1.1 204 No Content

Headers

ETag: <etag_value>

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 412 Precondition Failed

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Delete account linking partner

Request

DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

Parameter Description

Field Description Parameter Type Required?
skillId Unique identifier of skill Path Yes
stage Stage of the skill. Accepted value is development (case sensitive). Path Yes

Response

HTTP/1.1 204 No Content

Exceptions

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Service Error

HTTP/1.1 503 Service Unavailable

Last updated: Jun 13, 2022