StateTokenBuilder

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

```javascript
// 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 |
|---|---|---|
| `https://developers.google.com/apps-script/reference/script/state-token-builder#createToken()` | `String` | Constructs an encrypted string representation of the state token. |
| `https://developers.google.com/apps-script/reference/script/state-token-builder#withArgument(String,String)` | `https://developers.google.com/apps-script/reference/script/state-token-builder#` | Adds an argument to the token. |
| `https://developers.google.com/apps-script/reference/script/state-token-builder#withMethod(String)` | `https://developers.google.com/apps-script/reference/script/state-token-builder#` | Sets a callback function. |
| `https://developers.google.com/apps-script/reference/script/state-token-builder#withTimeout(Integer)` | `https://developers.google.com/apps-script/reference/script/state-token-builder#` | Sets the duration (in seconds) for which the token is valid. |

## Detailed documentation

### `createToken()`

Constructs an encrypted string representation of the state token.

```javascript
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.

```javascript
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


`https://developers.google.com/apps-script/reference/script/state-token-builder#` --- The state token builder, for chaining.

*** ** * ** ***

### `withMethod(method)`

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

```javascript
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


`https://developers.google.com/apps-script/reference/script/state-token-builder#` --- 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).

```javascript
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


`https://developers.google.com/apps-script/reference/script/state-token-builder#` --- The state token builder, for chaining.