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