Warning: This data is provided under the Google User Data Policy. Please review and comply with the policy. Failure to do so might result in project or account suspension.

Google 3P Authorization JavaScript Library for websites - API reference

This reference describes the Google 3P Authorization JavaScript Library API, which you can use to load authorization codes or access tokens from Google.

Method: google.accounts.oauth2.initCodeClient

The initCodeClient method initializes and returns a code client, with the configurations in the parameter.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

Data type: CodeClientConfig

The following table lists the properties of the CodeClientConfig data type.

Properties
client_id Required. The client ID for your application. You can find this value in the API Console.
scope Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values inform the consent screen that Google displays to the user.
redirect_uri Required for redirect UX. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 client, which you configured in the API Console and must conform to our Redirect URI validation rules. The property will be ignored by the popup UX.
callback Required for popup UX. The JavaScript function name that handles returned code response. The property will be ignored by the redirect UX.
state Optional. Recommended for redirect UX. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response.
enable_serial_consent Optional, defaults to true. If set to false, more granular Google Account permissions will be disabled for clients created before 2019. No effect for newer clients, since more granular permissions is always enabled for them.
hint Optional. If your application knows which user should authorize the request, it can use this property to provide a hint to Google. The email address for the target user. For more information, see the login_hint field in the OpenID Connect docs.
hosted_domain Optional. If your application knows the Workspace domain the user belongs to, use this to provide a hint to Google. For more information, see the hd field in the OpenID Connect docs.
ux_mode Optional. The UX mode to use for the authorization flow. By default, it will open the consent flow in a popup. Valid values are popup and redirect.
select_account Optional, defaults to 'false'. Boolean value to prompt the user to select an account.

Data type: CodeClient

The class has only one public method requestCode, which starts the OAuth 2.0 Code UX flow.

interface CodeClient {
  requestCode(): void;
}

Data type: CodeResponse

A CodeResponse JavaScript object will be passed to your callback method in the popup UX. In the redirect UX, the CodeResponse will be passed as URL parameters.

The following table lists the properties of the CodeResponse data type.

Properties
code The authorization code of a successful token response.
scope A space-delimited list of scopes that are approved by the user.
state The string value that your application uses to maintain state between your authorization request and the response.
error A single ASCII error code.
error_description Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred.
error_uri A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

Method: google.accounts.oauth2.initTokenClient

The initTokenClient method initializes and returns a token client, with the configurations in the parameter.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

Data type: TokenClientConfig

The following table lists the properties of the TokenClientConfig data type.

Properties
client_id Required. The client ID for your application. You can find this value in the API Console.
callback Required. The JavaScript function name that handles returned token response.
scope Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values inform the consent screen that Google displays to the user.
prompt Optional, defaults to 'select_account'. A space-delimited, case-sensitive list of prompts to present the user. Possible values are:
  • empty string The user will be prompted only the first time your app requests access. Cannot be specified with other values.
  • 'none' Do not display any authentication or consent screens. Must not be specified with other values.
  • 'consent' Prompt the user for consent.
  • 'select_account' Prompt the user to select an account.
enable_serial_consent Optional, defaults to true. If set to false, more granular Google Account permissions will be disabled for clients created before 2019. No effect for newer clients, since more granular permissions is always enabled for them.
hint Optional. If your application knows which user should authorize the request, it can use this property to provide a hint to Google. The email address for the target user. For more information, see the login_hint field in the OpenID Connect docs.
hosted_domain Optional. If your application knows the Workspace domain the user belongs to, use this to provide a hint to Google. For more information, see the hd field in the OpenID Connect docs.
state Optional. Not recommended. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response.

Data type: TokenClient

The class has only one public method requestAccessToken, which starts the OAuth 2.0 Token UX flow.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Arguments
overrideConfig OverridableTokenClientConfig Optional. The configurations to be overridden in this method.

Data type: OverridableTokenClientConfig

The following table lists the properties of the OverridableTokenClientConfig data type.

Properties
prompt Optional. A space-delimited, case-sensitive list of prompts to present the user.
enable_serial_consent Optional. If set to false, more granular Google Account permissions will be disabled for clients created before 2019. No effect for newer clients, since more granular permissions is always enabled for them.
hint Optional. If your application knows which user should authorize the request, it can use this property to provide a hint to Google. The email address for the target user. For more information, see the login_hint field in the OpenID Connect docs.
state Optional. Not recommended. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response.

Data type: TokenResponse

A TokenResponse JavaScript object will be passed to your callback method in the popup UX.

The following table lists the properties of the TokenResponse data type.

Properties
access_token The access token of a successful token response.
expires_in The lifetime in seconds of the access token.
hd The hosted domain the signed-in user belongs to.
prompt The prompt value that was used from the possible list of values specified by TokenClientConfig or OverridableTokenClientConfig.
token_type The type of the token issued.
scopes A space-delimited list of scopes that are approved by the user.
state The string value that your application uses to maintain state between your authorization request and the response.
error A single ASCII error code.
error_description Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred..
error_uri A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

Method: google.accounts.oauth2.hasGrantedAllScopes

Checks if the user granted all the specified scope or scopes.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Arguments
tokenResponse string Required. A valid access token.
firstScope string Required. The scope to check.
restScopes string[] Optional. Other scopes to check.
Returns
boolean True if all the scopes are granted.

Method: google.accounts.oauth2.hasGrantedAnyScope

Checks if the user granted any of the specified scope or scopes.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Arguments
tokenResponse string Required. A valid access token.
firstScope string Required. The scope to check.
restScopes string[] Optional. Other scopes to check.
Returns
boolean True if any of the scopes are granted.

Method: google.accounts.oauth2.revoke

The revoke method revokes all of the scopes that the user granted to the app. A valid access token is required to revoke the permission.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Arguments
accessToken string Required. A valid access token.
done function Optional. Callback function once the revoke action is done.