OAuth2#

The OAuth2 class provides a robust interface for managing OAuth 2.0 authorization flows in Scripting. It supports standard authorization code flows, PKCE (Proof Key for Code Exchange), access token renewal, and customizable token handling.

Constructor#

1new OAuth2(options: {
2  consumerKey: string
3  consumerSecret: string
4  authorizeUrl: string
5  accessTokenUrl?: string
6  responseType: string
7  contentType?: string
8})

Parameters#

Throws#

• Error if the configuration is invalid or instantiation fails.

Properties#

accessTokenBasicAuthentification: boolean#

Enable this to use HTTP Basic authentication when exchanging the authorization code for an access token. Default is false.

allowMissingStateCheck: boolean#

Disables CSRF protection based on state parameter validation. Use with caution. Default is false.

encodeCallbackURL: boolean#

Encodes the callback URL when generating the authorization URL. Required by some providers. Default is true.

encodeCallbackURLQuery: boolean#

Controls whether the entire query string is encoded. Some services (e.g., Imgur) require this to be false. Default is true.

Methods#

authorize(options): Promise<OAuthCredential>#

Initiates the OAuth2 authorization flow, opening a browser window for the user to log in and grant permissions.

1authorize(options: {
2  callbackURL?: string
3  scope: string
4  state: string
5  parameters?: Record<string, any>
6  headers?: Record<string, string>
7} & ({
8  codeVerifier: string
9  codeChallenge: string
10  codeChallengeMethod: string
11} | {
12  codeVerifier?: never
13  codeChallenge?: never
14  codeChallengeMethod?: never
15})): Promise<OAuthCredential>

Parameters#

Returns#

• A Promise that resolves to an OAuthCredential object containing tokens and metadata.

Throws#

• Error if the user denies authorization or a network/response error occurs.

Example#

1const oauth = new OAuth2({
2  consumerKey: 'your-client-id',
3  consumerSecret: 'your-client-secret',
4  authorizeUrl: 'https://provider.com/oauth/authorize',
5  accessTokenUrl: 'https://provider.com/oauth/token',
6  responseType: 'code'
7})
8
9const credential = await oauth.authorize({
10  scope: 'profile email',
11  state: 'secure_random_state',
12  callbackURL: Script.createOAuthCallbackURLScheme('my_oauth_script')
13})
14
15console.log(credential.oauthToken)

renewAccessToken(options): Promise<OAuthCredential>#

Exchanges a refresh token for a new access token from the provider.

1renewAccessToken(options: {
2  refreshToken: string
3  parameters?: Record<string, any>
4  headers?: Record<string, string>
5}): Promise<OAuthCredential>

Parameters#

Returns#

• A Promise that resolves to an updated OAuthCredential object.

Throws#

• Error if the refresh fails due to expired or revoked tokens.

Example#

1const newCredential = await oauth.renewAccessToken({
2  refreshToken: previous.oauthRefreshToken
3})
4
5console.log(newCredential.oauthToken)

OAuthCredential Type#

The OAuthCredential object contains all relevant information from a successful OAuth2 transaction.

1type OAuthCredential = {
2  oauthToken: string
3  oauthTokenSecret: string
4  oauthRefreshToken: string
5  oauthTokenExpiresAt: number | null
6  oauthVerifier: string
7  version: string
8  signatureMethod: string
9}

Field Descriptions#

Best Practices#

• Always verify state to protect against CSRF attacks unless explicitly disabled.
• Use Script.createOAuthCallbackURLScheme(name) to generate script-specific callback URLs.
• Securely store the oauthRefreshToken if long-term access is needed.
• Consider using PKCE for enhanced security, especially in public clients.