Class StateTokenBuilder

Allows scripts to create state tokens that can be used in callback APIs (like OAuth flows).

// Reusable function to generate a callback URL, assuming the script has been
// published as a web app (necessary to obtain the URL programmatically). If the
// script has not been published as a web app, set `var url` in the first line
// to the URL of your script project (which cannot be obtained
// programmatically).
function getCallbackURL(callbackFunction) {
  let url = ScriptApp.getService().getUrl();  // Ends in /exec (for a web app)
  url = `${
      url.slice(0, -4)}usercallback?state=`;  // Change /exec to /usercallback
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return url + stateToken;
}

Methods

Method	Return type	Brief description
`createToken()`	`String`	Constructs an encrypted string representation of the state token.
`withArgument(name, value)`	`StateTokenBuilder`	Adds an argument to the token.
`withMethod(method)`	`StateTokenBuilder`	Sets a callback function.
`withTimeout(seconds)`	`StateTokenBuilder`	Sets the duration (in seconds) for which the token is valid.

Detailed documentation

`createToken()`

Constructs an encrypted string representation of the state token.

const stateToken = ScriptApp.newStateToken().createToken();

Return

String — an encrypted string representing the token

`withArgument(name, value)`

Adds an argument to the token. This method can be called multiple times.

const stateToken =
    ScriptApp.newStateToken().withArgument('myField', 'myValue').createToken();

Parameters

Name	Type	Description
`name`	`String`	the name of the argument
`value`	`String`	the value of the argument

Return

StateTokenBuilder — the state token builder, for chaining

`withMethod(method)`

Sets a callback function. The default is a function named callback().

const stateToken =
    ScriptApp.newStateToken().withMethod('myCallback').createToken();

Parameters

Name	Type	Description
`method`	`String`	The name of the callback function, represented as a string without parentheses or arguments. You can use functions from included libraries, such as `Library.libFunction1`.

Return

StateTokenBuilder — the state token builder, for chaining

`withTimeout(seconds)`

Sets the duration (in seconds) for which the token is valid. The defaults is 60 seconds; the maximum duration is 3600 seconds (1 hour).

const stateToken = ScriptApp.newStateToken().withTimeout(60).createToken();

Parameters

Name	Type	Description
`seconds`	`Integer`	the duration for which the token is valid; the maximum value is `3600`

Return

StateTokenBuilder — the state token builder, for chaining