Class StateTokenBuilder

AI-generated Key Takeaways

• The StateTokenBuilder allows scripts to generate secure state tokens for use in callback APIs, such as OAuth flows.

• These tokens can be customized with arguments, a specific callback function, and a timeout period for enhanced security and functionality.

• ScriptApp.newStateToken() initiates the token creation process, offering methods like withArgument(), withMethod(), and withTimeout() for configuration.

• Finally, createToken() generates the encrypted string representation of the state token, ready to be used in your callback URL.

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