Account Linking Management REST API Reference

Use the Account Linking Management REST API to manage your skills information related to linking Alexa user accounts to other OAuth identity providers. For more details about account linking, see Account Linking Concepts for Alexa Skills.

You can also use the Alexa Skills Kit Command Line Interface (ASK CLI) to manage account linking information.

API endpoint

The endpoint of the Account Linking Management API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Account Linking Management API includes the following operations.

Operation HTTP method and URI

Delete account linking information

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

Get account linking information

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

Update account linking information

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

Delete account linking information

Remove account linking information from the specified skill in the specified skill stage.

Request

To remove account linking information, you make a DELETE request to the accountLinkingClient resource.

Request path and header example

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Account linking information deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get the account linking information associated with the specified skill.

To get account linking information, you make a GET request to the accountLinkingClient resource.

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the account linking information. For more details, see Account Linking Schemas. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "type": "AUTH_CODE",
    "authorizationUrl": "https://www.example.com/auth_url",
    "domains": ["www.example.com"],
    "clientId": "your.client.id.1",
    "scopes": [
        "permission.scope.a",
        "permission.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"
        }
    ],
    "voiceForwardAccountLinking": "ENABLED"
}

Response body properties

Property Description Type

type

Identifies the OAuth 2.0 grant type. For more details, see Grant types. Valid values: AUTH_CODE, IMPLICIT.

String

authorizationUrl

URL of your authorization server to which the Alexa app redirects the customer to enter login credentials for your system.

String

domains

List of additional domains from which the authorization URL fetches content.

Array of string

clientId

Unique public string that identifies the customer.

String

scopes

List of permissions that your skill requests from the customer.
For more details, see permissions.

Array of string

accessTokenUrl

URL of your token server that can receive access and refresh token requests.

String

accessTokenScheme

Type of client authentication scheme.
Valid values: HTTP_BASIC, 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

List of URLs by mobile platform used to start account linking.

Array of objects

authorizationUrlsByPlatform[].platformType

Type of mobile platform that the customer uses to perform account linking.
Valid values: iOS, Android.

String

authorizationUrlsByPlatform[].platformAuthorizationUrl

OAuth 2.0 authorization URL to open the app to authenticate the customer.
Valid values: iOS, Android.

String

voiceForwardAccountLinking

Specifies whether the skill supports voice-forward account linking.
Valid values: ENABLED, DISABLED.

String

Status Description

200 OK

Response body contains the account linking information. The response header contains an ETag that identifies the current version of the account linking information for the specified skill.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update account linking information for the specified skill.

To update account linking information, you make a PUT request to the accountLinkingClient resource.

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

etag

Header

Current version of the account linking information. Use Get account linking information to get the current version.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "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"
    }
}

Request body properties

Property Description Type Required

accountLinkingRequest

Defines the updates to the account linking information.

Object

Yes

accountLinkingRequest.type

Identifies the OAuth 2.0 grant type. For more details, see Grant types. For smart home and video skills, you must set to AUTH_CODE.
Valid values: AUTH_CODE, IMPLICIT.

String

No

accountLinkingRequest.authorizationUrl

URL of your authorization server to which the Alexa app redirects the customer to enter login credentials for your system.

String

No

accountLinkingRequest.domains

List of additional domains from which the authorization URL fetches content. You can specify up to 15 domains.

Array of string

No

accountLinkingRequest.clientId

Unique public string that identifies the customer.

String

No

accountLinkingRequest.scopes

List of permissions that your skill requests from the customer.
For more details, see permissions. Required for smart home and video skills.

Array of string

No

accountLinkingRequest.accessTokenUrl

URL of your token server that can receive access and refresh token requests. Required when type is AUTH_CODE.

String

No

accountLinkingRequest.accessTokenScheme

Type of client authentication scheme. Required when type is AUTH_CODE.
Valid values: HTTP_BASIC, REQUEST_BODY_CREDENTIALS.

String

No

accountLinkingRequest.defaultTokenExpirationInSeconds

Number of seconds that the access token is valid. Required when type is AUTH_CODE.

Integer

No

accountLinkingRequest.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

No

accountLinkingRequest.authorizationUrlsByPlatform

List of URLs by mobile platform used to start account linking.

Array of objects

No

accountLinkingRequest.authorizationUrlsByPlatform[].platformType

Type of mobile platform that the customer uses to perform account linking.
Valid values: iOS, Android.

String

Yes

accountLinkingRequest.authorizationUrlsByPlatform[].platformAuthorizationUrl

OAuth 2.0 authorization URL to open the app to authenticate the customer.
Valid values: iOS, Android.

String

Yes

accountLinkingRequest.skipOnEnablement

Indicates whether to start account link when the customer enables the skill.
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.

Boolean

No

accountLinkingRequest.voiceForwardAccountLinking

Specifies whether the skill supports voice-forward account linking.
Valid values: ENABLED, DISABLED. Default: DISABLED.

String

No

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

Status Description

200 OK

Account linking information updated successfully. The response header contains an ETag that identifies the current version of the account linking information for the specified skill.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Last updated: Sep 08, 2023