Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
Before you can use Amazon Device Messaging (ADM) to send a message to an instance of your app, on the server side you must have:
  • Obtained and stored the app instance’s registration ID; for more details, see Integrate Your App.
  • Exchanged your OAuth client credentials for a current access token. This document describes that process.
To send a message and for information about the high-level architecture of ADM, see Send a Message and Overview of ADM.

Client credentials and access tokens

To acquire an access token, your server provides ADM servers with your OAuth client credentials. Your client credentials are assigned to you by Amazon and are two pieces of data that are unique to your app: a client_id and a client_secret value. Your servers use both pieces of your client credentials in their requests to obtain ADM access tokens. For information about how to get your client credentials, see Obtain Credentials. An access token is short-lived metadata that authenticates your server’s identity to ADM, so that you can send messages. When you send a message using ADM, that message request must include an access token. Although a server only uses a single access token at any given time, you must obtain a new access token when an old one expires. Also, although it is possible to share an access token across multiple servers, it is typically more convenient for each of your servers to obtain their own access token and independently request, track, and use it for sending messages.

Request format

Your servers obtain their access tokens by providing your client credentials in a request call to ADM servers. You can use this same request to acquire an initial access token or to obtain a new one when a prior access token has expired. To obtain an access token, your server issues a POST request on an HTTPS connection. The request looks similar to this:
The request itself consists of two parts: a header and a message body. The header must contain the following field: For the content of the message body, you must provide a URL-encoded string containing the following parameters:

Response format

After successfully receiving and interpreting your POST request message, ADM sends your server an HTTP response message that looks similar to this:
The header for the response contains the following fields:
HeaderDescriptionExample
X-Amzn-RequestIdA value created by ADM that uniquely identifies the request. In the unlikely event that you have problems with ADM, Amazon can use this value to troubleshoot the problem.X-Amzn-RequestId: <hexidecimal request ID>
Content-TypeThe content type of the resource: application/jsonContent-Type: application/json
When one of your servers successfully requests an access token you receive a 200 status code response, and the message body for the response to that request includes both the access token and its lifespan in seconds.
ParameterDescriptionExample
access_tokenAn access token that must be used for all enqueue requests."access_token":"<hexidecimal access token>"
expires_inThe duration in seconds of the access token lifetime. For example, the value “3600” denotes that the access token expires in one hour from the time the response was generated."expires_in":3600
token_typeThe type of the token issued. One of the supported token types. Currently only “Bearer” tokens are supported."token_type":"Bearer"
scopeThe scope specified in the access token request. Value will be messaging:push."scope":"messaging:push"
ADM returns a non-200 error status code for an unsuccessful request. In the case of a non-200 code, the response message might contain the following parameter in the body of the JSONObject:
  • reason: The reason the request was not accepted.
The following table lists possible error status codes for an access token request.
CodeDescriptionExample
400Reasons for this response include: * The content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded. * The request is missing a required parameter: client_id, client_secret, scope, grant-type. * The request is otherwise malformed. * ADM has not been enabled for your security profile. See Obtain Credentials.INVALID_REQUEST
400The client is not authorized for the requested operation.UNAUTHORIZED_CLIENT
400The grant type is not supported by the authorization server. In other words, it is not client_credentials.UNSUPPORTED_GRANT_TYPE
400The requested scope is invalid. In other words, it is not messaging:push.INVALID_SCOPE
401The client authentication failed.INVALID_CLIENT
500There was an internal server error. The requester can retry the request.SERVER_ERROR
503The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. See the HTTP/1.1 specification, section 14.37, for possible formats for the Retry-After value.SERVICE_UNAVAILABLE

Making the token request and handling the response

The following code sample is an example of how your server software might send the access token request and handle the ADM servers’ response:
Last modified on September 21, 2022