We announced the upcoming end-of-support for AWS SDK for JavaScript v2.
We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Class: AWS.Token

Inherits:
Object
  • Object
show all
Defined in:
lib/token.js

Overview

Represents AWS token object, which contains token, and optional expireTime. Creating a Token object allows you to pass around your token to configuration and service objects.

Note that this class typically does not need to be constructed manually, as the AWS.Config and AWS.Service classes both accept simple options hashes with the two keys. The token from this object will be used automatically in operations which require them.

Expiring and Refreshing Token

Occasionally token can expire in the middle of a long-running application. In this case, the SDK will automatically attempt to refresh the token from the storage location if the Token class implements the refresh() method.

If you are implementing a token storage location, you will want to create a subclass of the Token class and override the refresh() method. This method allows token to be retrieved from the backing store, be it a file system, database, or some network storage. The method should reset the token attributes on the object.

Constructor Summary collapse

Property Summary collapse

Method Summary collapse

Constructor Details

new AWS.Token(options) ⇒ void

Creates a Token object with a given set of information in options hash.

Examples:

Create a token object

var token = new AWS.Token({ token: 'token' });

Options Hash (options):

  • token (String) —

    represents the literal token string.

  • expireTime (Date) —

    field representing the time at which the token expires.

Property Details

expired ⇒ Boolean (readwrite)

Returns whether the token is expired and require a refresh. Used in conjunction with expireTime.

Returns:

  • (Boolean) —

    whether the token is expired and require a refresh. Used in conjunction with expireTime.

expireTime ⇒ Date (readwrite)

Returns a time when token should be considered expired. Used in conjunction with expired.

Returns:

  • (Date) —

    a time when token should be considered expired. Used in conjunction with expired.

expiryWindow ⇒ Integer, Number (static, readwrite)

Default Value:

AWS.Token.expiryWindow = 15

token ⇒ String (readwrite)

Returns represents the literal token string. This will typically be a base64 encoded string.

Returns:

  • (String) —

    represents the literal token string. This will typically be a base64 encoded string.

Method Details

get(callback) ⇒ void

Gets the existing token, refreshing them if they are not yet loaded or have expired. Users should call this method before using refresh(), as this will not attempt to reload token when they are already loaded into the object.

Callback (callback):

  • function(err) { ... }

    When this callback is called with no error, it means either token do not need to be refreshed or refreshed token information has been loaded into the object (as the token property).

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled

getPromise() ⇒ Promise

Returns a 'thenable' promise. Gets the existing token, refreshing it if it's not yet loaded or have expired. Users should call this method before using refresh(), as this will not attempt to reload token when it's already loaded into the object.

Two callbacks can be provided to the then method on the returned promise. The first callback will be called if the promise is fulfilled, and the second callback will be called if the promise is rejected.

Examples:

Calling the getPromise method.

var promise = tokenProvider.getPromise();
promise.then(function() { ... }, function(err) { ... });

Callbacks:

  • function() { ... }

    Called if the promise is fulfilled. When this callback is called, it means either token does not need to be refreshed or refreshed token information has been loaded into the object (as the token property).

  • function(err) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled.

Returns:

  • (Promise) —

    A promise that represents the state of the get call.

needsRefresh() ⇒ Boolean

Note:

Subclasses should override this method to provide custom refresh logic.

Returns whether the Token object should call refresh().

Returns:

  • (Boolean) —

    whether the Token object should call refresh()

refresh(callback) ⇒ void

Note:

Subclasses should override this class to reset the token on the token object and then call the callback with any error information.

Refreshes the token. Users should call get() before attempting to forcibly refresh token.

Callback (callback):

  • function(err) { ... }

    When this callback is called with no error, it means refreshed token information has been loaded into the object (as the token property).

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled

See Also:

refreshPromise() ⇒ Promise

Returns a 'thenable' promise. Refreshes the token. Users should call get() before attempting to forcibly refresh token.

Two callbacks can be provided to the then method on the returned promise. The first callback will be called if the promise is fulfilled, and the second callback will be called if the promise is rejected.

Examples:

Calling the refreshPromise method.

var promise = tokenProvider.refreshPromise();
promise.then(function() { ... }, function(err) { ... });

Callbacks:

  • function() { ... }

    Called if the promise is fulfilled. When this callback is called, it means refreshed token information has been loaded into the object (as the token property).

  • function(err) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled.

Returns:

  • (Promise) —

    A promise that represents the state of the refresh call.