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

DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 account linking information

Get the account linking information associated with the specified skill.

Request

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

Request path and header example

GET /v1/skills/{skillId}/stages/{stageV2}/accountLinkingClient
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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 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",
    "pkceConfiguration": {
        "status": "ENABLED",
        "codeChallengeMethod": "S256"
    }
}

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
`accountLinkingRequest.pkceConfiguration`	Indicates whether the authorization server supports Proof Key for Code Exchange (PKCE) with SHA-256 security measures.	Object
`accountLinkingRequest.pkceConfiguration.status`	Authorization server PKCE status. Valid values: `ENABLED`, `DISABLED`.	String
`accountLinkingRequest.pkceConfiguration.codeChallengeMethod`	Method used to create a code challenge. Account linking supports the SHA-256 code challenge method only. Valid value: `S256`.	String

HTTP status codes

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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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

Update account linking information for the specified skill.

Request

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

Request path and header example

PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
Host: api.amazonalexa.com
Content-Type: application/json
If-Match: {etag}
Authorization: Bearer {access token}

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
`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

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

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
`accountLinkingRequest.pkceConfiguration`	Indicates whether the authorization server supports Proof Key for Code Exchange (PKCE) with SHA-256 security measures.	Object	No
`accountLinkingRequest.pkceConfiguration.status`	Authorization server PKCE status. Valid values: `ENABLED`, `DISABLED`.	String	Yes
`accountLinkingRequest.pkceConfiguration.codeChallengeMethod`	Method used to create a code challenge. Account linking supports the SHA-256 code challenge method only. Valid value: `S256`.	String	Yes

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
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 Started

Plan and Implement

Reference

Account Linking Management REST API Reference

API endpoint

Authentication

Operations

Delete account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Get account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Update account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

​API endpoint

​Authentication

​Operations

​Delete account linking information

​Request

​Request path and header example

​Request path and header parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Get account linking information

​Request

​Request path and header example

​Request path and header parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Update account linking information

​Request

​Request path and header example

​Request path and header parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Related topics

API endpoint

Authentication

Operations

Delete account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Get account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Update account linking information

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Related topics