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. |
include_granted_scopes |
Optional, defaults to true . Enables applications to use incremental
authorization to request access to additional scopes in context. If you set
this parameter's value to false and the authorization request is granted, then
the new access token will only cover any scopes to which the scope requested
in this CodeClientConfig .
|
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 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_granular_consent |
Optional, defaults to true . If set to false , more granular Google Account permissions
would be disabled for OAuth client IDs created before 2019. If both enable_granular_consent and enable_serial_consent are set, only enable_granular_consent
value would take effect and enable_serial_consent value would be ignored.No effect for newer OAuth client IDs, since more granular permissions is always enabled for them. |
enable_serial_consent |
Deprecated, you should use enable_granular_consent instead. This
has the same effect as enable_granular_consent . Existing applications
that use enable_serial_consent can continue to do so, but you are
encouraged to update your code to use enable_granular_consent in
your next application update.
|
login_hint |
Optional. If your application knows which user should authorize the request, it can use this property to provide a login hint to Google. When successful, account selection is skipped. The email address or ID token sub field value for the target user.
For more information, see the login_hint field in the OpenID Connect documentation.
|
hd |
Optional. If your application knows the Workspace domain the user belongs to, use this to provide a hint to Google. When successful, user accounts are limited to or pre-selected for the provided domain.
For more information, see the hd field in the OpenID Connect documentation.
|
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. |
error_callback |
Optional. The JavaScript function that handles some non-OAuth errors, such as the
popup window is failed to open; or closed before an OAuth response is
returned.
The `type` field of the input parameter gives the detailed reason.
|
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 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. |
include_granted_scopes |
Optional, defaults to true . Enables applications to use incremental
authorization to request access to additional scopes in context. If you set
this parameter's value to false and the authorization request is granted, then
the new access token will only cover any scopes to which the scope requested
in this TokenClientConfig .
|
prompt |
Optional, defaults to 'select_account'. A space-delimited,
case-sensitive list of prompts to present the user. Possible values are:
|
enable_granular_consent |
Optional, defaults to true . If set to false , more granular Google Account permissions
would be disabled for OAuth client IDs created before 2019. If both enable_granular_consent and enable_serial_consent are set, only enable_granular_consent
value would take effect and enable_serial_consent value would be ignored.No effect for newer OAuth client IDs, since more granular permissions is always enabled for them. |
enable_serial_consent |
Deprecated, you should use enable_granular_consent instead. This
has the same effect as enable_granular_consent . Existing applications
that use enable_serial_consent can continue to do so, but you are
encouraged to update your code to use enable_granular_consent in
your next application update.
|
login_hint |
Optional. If your application knows which user should authorize the request, it can use this property to provide a login hint to Google. When successful, account selection is skipped. The email address or ID token sub field value for the target user.
For more information, see the login_hint field in the OpenID Connect documentation.
|
hd |
Optional. If your application knows the Workspace domain the user belongs to, use this to provide a hint to Google. When successful, user accounts are limited to or pre-selected for the provided domain.
For more information, see the hd field in the OpenID Connect documentation.
|
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. |
error_callback |
Optional. The JavaScript function that handles some non-OAuth errors, such as the
popup window is failed to open; or closed before an OAuth response is
returned.
The `type` field of the input parameter gives the detailed reason.
|
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 | |
---|---|
scope |
Optional. 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. |
include_granted_scopes |
Optional, defaults to true . Enables applications to use incremental
authorization to request access to additional scopes in context. If you set
this parameter's value to false and the authorization request is granted, then
the new access token will only cover any scopes to which the scope requested
in this OverridableTokenClientConfig .
|
prompt |
Optional. A space-delimited, case-sensitive list of prompts to present the user. |
enable_granular_consent |
Optional, defaults to true . If set to false , more granular Google Account permissions
would be disabled for OAuth client IDs created before 2019.If both enable_granular_consent and enable_serial_consent are set, only enable_granular_consent
value would take effect and enable_serial_consent value would be ignored.No effect for newer OAuth client IDs, since more granular permissions is always enabled for them. |
enable_serial_consent |
Deprecated, you should use enable_granular_consent instead. This
has the same effect as enable_granular_consent . Existing applications
that use enable_serial_consent can continue to do so, but you are
encouraged to update your code to use enable_granular_consent in
your next application update.
|
login_hint |
Optional. If your application knows which user should authorize the request, it can use this property to provide a login hint to Google. When successful, account selection is skipped. The email address or ID token sub field value for the target user.
For more information, see the login_hint field in the OpenID Connect documentation.
|
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. |
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.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 |
TokenResponse
|
Required. A TokenResponse
object.
|
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 |
TokenResponse
|
Required. A TokenResponse
object.
|
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. |
callback |
function | Optional. RevocationResponse handler. |
Data type: RevocationResponse
A RevocationResponse
JavaScript object will be passed to your callback method.
The following table lists the properties of the RevocationResponse
data type.
Properties | |
---|---|
successful |
Boolean. true on succeeded, false on failure. |
error |
String. Undefined on success. A single ASCII error code. This includes but not limited to the standard OAuth
2.0 error codes. Common errors for revoke method:
|
error_description |
String. Undefined on success. Human-readable ASCII text provides additional information on
error property. Developers can use this to better understand
the error that occurred. The error_description string is in English only.
For the common errors listed in error the corresponding error_description :
|