Menu
Amazon DevPay
Developer Guide (API Version 2007-12-01)

RefreshUserToken

Description

Occasionally AWS might change the contents of the user token to support new functionality. The RefreshUserToken action accepts a user token and returns an up-to-date version of that token. You can then use the updated token to take advantage of the new functionality. Even if the user token you send is already the latest version, the action succeeds and returns the latest version of the user token.

For example, after May 15, 2008, the ActivateHostedProduct action began returning a new version of the user token that allows you to use query string authentication with your web product without having to pass the product token in clear text in the URL (for more information, see Query String Authentication with Web Products). You can exchange your existing web product user tokens for the new version by using RefreshUserToken.

Important

Desktop products must use REST-Query to access this action; they cannot use SOAP.

Request Authentication

Requests for RefreshUserToken must be made over HTTPS and authenticated by AWS. For more information, see Authentication of REST-Query Requests (for REST-Query) or Authentication of SOAP Requests (for SOAP, which is only allowed for web products).

Request Parameters

Name Description Required

Action

The License Service action to perform. Set this to RefreshUserToken.

Type: String

Default: None

Condition: Required for REST-Query requests (for more information, see REST-Query Requests). For SOAP requests, the action is automatically indicated in the SOAP request's root element (for more information, see SOAP Requests).

Conditional

AdditionalTokens

A list of tokens. Currently, the only token you might need to provide in this list is the product token, which you obtain during product registration. For more information about registration, see Registering Your Product. The product token is prefixed with the literal string {ProductToken}.

Type: String

Default: None

Condition: You must provide the product token if the product is a desktop product, or if it's a web product and the user token was originally created from a call to ActivateHostedProduct made on or before May 15, 2008.

Conditional

AWSAccessKeyId

The Access Key ID associated with the Secret Access Key used to sign the request. For desktop products, this is the customer's Access Key ID. For web products, this is your Access Key ID. For more information about Access Key IDs, see Your AWS Access Credentials.

Type: String

Default: None

Condition: Required for REST-Query requests. Not applicable to SOAP requests.

Conditional

Expires

The date and time at which the signature included in the request expires.

Type: String in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard.

Default: None

Condition: REST-Query requests must include either the Timestamp parameter or the Expires parameter, but not both. For information about handling message expiration for SOAP requests, see Message Expiration.

Conditional

Signature

A request signature. Desktop products must sign the request with the customer's Secret Access Key. Web products must sign the request with your Secret Access Key. For more information about creating the signature, see Calculating an HMAC-SHA1 Request Signature.

Type: String

Default: None

Condition: Required for REST-Query requests. Not applicable to SOAP requests.

Conditional

SignatureVersion

A legacy parameter AWS requires. Set this value to 1.

Type: String

Default: None

Condition: Required for REST-Query requests. Not applicable to SOAP requests.

Conditional

Timestamp

The date and time the request is signed.

Type: String in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard.

Default: None

Condition: Authenticated REST-Query requests must include either the Timestamp parameter or the Expires parameter, but not both. For information about handling message expiration for SOAP requests, see Message Expiration.

Conditional

UserToken

The unexpired user token you want to refresh.

Type: String

Default: None

Yes

Version

The version of the API to use. You must set this to 2008-04-28 (or newer) to use RefreshUserToken.

Type: String

Default: 2007-06-05

Condition: Highly recommended for REST-Query requests. Not applicable to SOAP requests (the API version is indicated in the namespace).

Conditional

Response Elements

The response to this action contains the following element in addition to the elements returned in all successful responses. For more information, see Structure of a Successful Response.

Name Description

UserToken

The refreshed user token, which is prefixed with the literal string {UserToken}.

Type: String

Ancestor: RefreshUserTokenResult

Errors

The errors listed in the following table are returned in addition to the errors returned by all actions. For more information, see Errors.

Important

We might throttle requests to the License Service as necessary. When we throttle, we return a 503 (service unavailable) HTTP status code. Your system should be prepared to retry any request that receives a 503 code.

Name Description

InvalidClientTokenId

Authentication failure. Note that an invalid user token or product token might also trigger this error.

Action to take: Make sure you have copied the product token and user token correctly and that you use the correct credentials when you sign the request. You can view the product token for your product at any time by clicking View Product Details on your DevPay Activity page (at http://aws.amazon.com/devpayactivity).

InvalidProductToken

The product token is invalid for the signer.

Action to take: Make sure you have copied the product token correctly and that you use the correct credentials when you sign the request. You can view the product token for your product at any time by clicking View Product Details on your DevPay Activity page (at http://aws.amazon.com/devpayactivity).

InvalidParameterValue

One or more of the parameters required in the request is missing or invalid.

Examples

The following example REST-Query request refreshes a user token.

Sample Request

https://ls.amazonaws.com/
?Action=RefreshUserToken
&AdditionalTokens={ProductToken}YLFRL3e4lOHTgGSQa8BOKA....[long encoded token]... 
&UserToken={UserToken}AAAHVXNlclRrbgfOpSykBAXO7g/zG....[long encoded token]...
&Version=2008-04-28
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
&Timestamp=2008-05-19T12:00:00Z
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEEXAMPLE=
&SignatureVersion=1

Sample Response


<RefreshUserTokenResponse>
   <RefreshUserTokenResult>
      <UserToken>
         {UserToken}DRTNXLBkql7XfpfOwrEPuD4Rl/Qm....[long encoded token]...
      </UserToken>
   <RefreshUserTokenResult>
   <ResponseMetadata>
      <RequestId>
         cb919c0a-9bce-4afe-9b48-9bdf2412bb67
      </RequestId>
   </ResponseMetadata>
</RefreshUserTokenResponse>