Google Sign-In JavaScript client reference

This reference describes the JavaScript client methods and attributes you will use to implement Google Sign-In in your web applications.

If you encounter any issue using the library, please report it to our GitHub repository.

Auth Setup

Load the Google APIs platform library to create the gapi object:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

After the platform library loads, load the auth2 library:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Initializes the GoogleAuth object. You must call this method before calling gapi.auth2.GoogleAuth's methods.

When you initialize the GoogleAuth object, you configure the object with your OAuth 2.0 client ID and any additional options you want to specify. Then, if the user has already signed in, the GoogleAuth object restores the user's sign-in state from the previous session.

Arguments
params An object containing key-value pairs of client configuration data. See gapi.auth2.ClientConfig for the different properties configurable. For example: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Returns
gapi.auth2.GoogleAuth The gapi.auth2.GoogleAuth object. Use the then() method to get a Promise that is resolved when the gapi.auth2.GoogleAuth object finishes initializing.

GoogleAuth.then(onInit, onError)

Calls the onInit function when the GoogleAuth object is fully initialized. If an error is raised while initializing (this can happen in old unsupported browsers), the onError function will be called instead.

Arguments
onInit The function called with the GoogleAuth object when it is fully initialized.
onError The function called with an object containing an error property, if GoogleAuth failed to initialize.
Returns
Promise A Promise that is fulfilled when the onInit function has completed, or rejected if an initialization error was raised. It resolves with the returned value from the onInit function, if any.

Error Codes

idpiframe_initialization_failed
Failed to initialize a required iframe from Google, for instance, due to an unsupported environment. A details property will give more information on the error raised.

gapi.auth2.ClientConfig

Interface that represents the different configuration parameters for the gapi.auth2.init method.

Parameters
client_id string Required. The app's client ID, found and created in the Google Developers Console.
cookie_policy string The domains for which to create sign-in cookies. Either a URI, single_host_origin, or none. Defaults to single_host_origin if unspecified.
scope string The scopes to request, as a space-delimited string. Optional if fetch_basic_profile is not set to false.
fetch_basic_profile boolean Fetch users' basic profile information when they sign in. Adds 'profile', 'email' and 'openid' to the requested scopes. True if unspecified.
hosted_domain string The G Suite domain to which users must belong to sign in. This is susceptible to modification by clients, so be sure to verify the hosted domain property of the returned user. Use GoogleUser.getHostedDomain() on the client, and the hd claim in the ID Token on the server to verify the domain is what you expected.
ux_mode string The UX mode to use for the sign-in flow. By default, it will open the consent flow in a popup. Valid values are popup and redirect.
redirect_uri string If using ux_mode='redirect', this parameter allows you to override the default redirect_uri that will be used at the end of the consent flow. The default redirect_uri is the current URL stripped of query parameters and hash fragment.

Authentication

GoogleAuth is a singleton class that provides methods to allow the user to sign in with a Google account, get the user's current sign-in status, get specific data from the user's Google profile, request additional scopes, and sign out from the current account.

gapi.auth2.getAuthInstance()

Returns the GoogleAuth object. You must initialize the GoogleAuth object with gapi.auth2.init() before calling this method.

Returns
gapi.auth2.GoogleAuth The gapi.auth2.GoogleAuth object. Use this object to call gapi.auth2.GoogleAuth's methods.

GoogleAuth.isSignedIn.get()

Returns whether the current user is currently signed in.

Returns
Boolean true if the user is signed in, or false if the user is signed out or the GoogleAuth object isn't initialized.

GoogleAuth.isSignedIn.listen(listener)

Listen for changes in the current user's sign-in state.

Arguments
listener A function that takes a boolean value. listen() passes true to this function when the user signs in, and false when the user signs out.

GoogleAuth.signIn()

Signs in the user with the options specified to gapi.auth2.init().

Returns
Promise A Promise that is fulfilled with the GoogleUser instance when the user successfully authenticates and grants the requested scopes, or rejected with an object containing an error property if an error happened (see below for error codes).

Error codes

See GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Signs in the user using the specified options.

Arguments
options Either:
  • A gapi.auth2.SignInOptions object containing key-value pairs of sign-in parameters. For example: 
    {
  scope: 'profile email'
}
  • An instance of gapi.auth2.SigninOptionsBuilder. For example:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Returns
Promise A Promise that is fulfilled with the GoogleUser instance when the user successfully authenticates and grants the requested scopes, or rejected with an object containing an error property if an error happened (see below for error codes).

Error codes

popup_closed_by_user
The user closed the popup before finishing the sign in flow.
access_denied
The user denied the permission to the scopes required.
immediate_failed
No user could be automatically selected without prompting the consent flow. Error raised when using signIn with prompt: 'none' option. This option should not be required to use, as gapi.auth2.init will automatically sign in the user if previously signed in during a previous session.

gapi.auth2.SignInOptions

Interface that represents the different configuration parameters for the GoogleAuth.signIn(options) method.

Parameters
prompt string Forces a specific mode for the consent flow. Optional.
The possible values are:
  • consent
    The authorization server prompts the user for consent before returning information to the application.
  • select_account
    The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for.
  • none (not recommended)
    The authorization server will not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not previously consented to the requested scopes.
    As gapi.auth2.init will automatically sign in a user to the application if previously signed in, calling signIn({prompt: 'none'}) will usually fail.
scope string The scopes to request, as a space-delimited string, on top of the scopes defined in the gapi.auth2.init params. Optional if fetch_basic_profile is not set to false.
ux_mode string The UX mode to use for the sign-in flow. By default, it will open the consent flow in a popup. Valid values are popup and redirect.
redirect_uri string If using ux_mode='redirect', this parameter allows you to override the default redirect_uri that will be used at the end of the consent flow. The default redirect_uri is the current URL stripped of query parameters and hash fragment.

GoogleAuth.signOut()

Signs out the current account from the application.

Returns
Promise A Promise that is fulfilled when the user has been signed out.

GoogleAuth.disconnect()

Revokes all of the scopes that the user granted.

GoogleAuth.grantOfflineAccess(options)

Get permission from the user to access the specified scopes offline.

Arguments
options A gapi.auth2.OfflineAccessOptions object containing key-value pairs of parameters. For example: 
{
  scope: 'profile email'
}
Returns
Promise A Promise that is fulfilled when the user grants the requested scopes, passing an object containing the authorization code to the Promise's fulfillment handler. For example: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Error codes

popup_closed_by_user
The user closed the popup before finishing the consent flow.
access_denied
The user denied the permission to the scopes required.
immediate_failed
No user could be automatically selected without prompting the consent flow. Error raised when using signIn with prompt: 'none' option. This option should not be required to use, as gapi.auth2.init will automatically sign in the user if previously signed in during a previous session.

gapi.auth2.OfflineAccessOptions

Interface that represents the different configuration parameters for the GoogleAuth.grantOfflineAccess(options) method.

Parameters
prompt string Forces a specific mode for the consent flow. Optional.
The possible values are:
  • consent
    The authorization server prompts the user for consent before returning information to the application.
  • select_account
    The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for.
scope string The scopes to request, as a space-delimited string, on top of the scopes defined in the gapi.auth2.init params. Optional if fetch_basic_profile is not set to false.

GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)

Attaches the sign-in flow to the specified container's click handler.

Arguments
container The ID of, or a reference to, the div element to which to attach the click handler.
options An object containing key-value pairs of parameters. See GoogleAuth.signIn().
onsuccess The function to call after sign-in completes.
onfailure The function to call if sign-in fails.

Users

A GoogleUser object represents one user account. GoogleUser objects are typically obtained by calling GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Returns a GoogleUser object that represents the current user. Note that in a newly-initialized GoogleAuth instance, the current user has not been set. Use the currentUser.listen() method or the GoogleAuth.then() to get an initialized GoogleAuth instance.

Returns
GoogleUser The current user

GoogleAuth.currentUser.listen(listener)

Listen for changes in currentUser.

Arguments
listener A function that takes a GoogleUser parameter. listen passes this function a GoogleUser instance on every change that modifies currentUser.

GoogleUser.getId()

Get the user's unique ID string.

Returns
String The user's unique ID

GoogleUser.isSignedIn()

Returns true if the user is signed in.

Returns
Boolean True if the user is signed in

GoogleUser.getHostedDomain()

Get the user's G Suite domain if the user signed in with a G Suite account.

Returns
String The user's G Suite domain

GoogleUser.getGrantedScopes()

Get the scopes that the user granted as a space-delimited string.

Returns
String The scopes granted by the user

GoogleUser.getBasicProfile()

Get the user's basic profile information.

Returns
gapi.auth2.BasicProfile You can retrieve the properties of gapi.auth2.BasicProfile with the following methods:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

Get the response object from the user's auth session.

Arguments
includeAuthorizationData Optional: A boolean that specifies whether to always return an access token and scopes. By default, the access token and requested scopes are not returned when fetch_basic_profile is true (the default value) and no additional scopes are requested.
Returns
gapi.auth2.AuthResponse A gapi.auth2.AuthResponse object.

GoogleUser.reloadAuthResponse()

Forces a refresh of the access token, and then returns a Promise for the new AuthResponse.

Returns
Promise A Promise that is fulfilled with the reloaded gapi.auth2.AuthResponse when reloading the OAuth token is done.

gapi.auth2.AuthResponse

The response returned when calling GoogleUser.getAuthResponse(includeAuthorizationData) or GoogleUser.reloadAuthResponse() methods.

Properties
access_token string The Access Token granted.
id_token string The ID Token granted.
scope string The scopes granted in the Access Token.
expires_in number The number of seconds until the Access Token expires.
first_issued_at number The timestamp at which the user first granted the scopes requested.
expires_at number The timestamp at which the Access Token will expire.

GoogleUser.hasGrantedScopes(scopes)

Returns true if the user granted the specified scopes.

Arguments
scopes A space-delimited string of scopes.
Returns
Boolean True if the scopes were granted

GoogleUser.grant(options)

Request additional scopes to the user.

See GoogleAuth.signIn() for the list of parameters and the error code.

GoogleUser.grantOfflineAccess(options)

Get permission from the user to access the specified scopes offline.

Arguments
options A gapi.auth2.OfflineAccessOptions object containing key-value pairs of parameters. For example: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Revokes all of the scopes that the user granted for the application.

UI elements

gapi.signin2.render(id, options)

Renders a sign-in button in the element with the given ID, using the settings specified by the options object.

Arguments
id The ID of the element in which to render the sign-in button.
options An object containing the settings to use to render the button. For example: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
You can specify the following options:
Parameters
scope The scopes to request when the user signs in (default: profile).
width The width of the button in pixels (default: 120).
height The height of the button in pixels (default: 36).
longtitle Display long labels such as "Sign in with Google" rather than "Sign in" (default: false). When you use long titles, you should increase the width of the button from its default.
theme The color theme of the button: either light or dark (default: light).
onsuccess The callback function to call when a user successfully signs in. This function must take one argument: an instance of gapi.auth2.GoogleUser (default: none).
onfailure The callback function to call when sign-in fails. This function takes no arguments (default: none).

Advanced

gapi.auth2.authorize(params, callback)

Performs a one time OAuth 2.0 authorization. Depending on the parameters used, this will open a popup to the Google sign-in flow or try to load the requested response silently, without user interaction.

Some use cases where this method is useful include:

  • Your application only needs to requests a Google API endpoint once, for instance to load the user's favorite YouTube videos the first time they sign in.
  • Your application has its own session management infrastructure, and it only requires the ID Token once to identify the user in your backend.
  • Several Client IDs are used within the same page.
Arguments
params An object containing key-value pairs of configuration data. See gapi.auth2.AuthorizeConfig for the different properties configurable. For example: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback A function called with a gapi.auth2.AuthorizeResponse object after the request has been completed (either successfully or with a failure).

Example

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Error codes

idpiframe_initialization_failed
Failed to initialize a required iframe from Google, for instance, due to an unsupported environment. A details property will give more information on the error raised.
popup_closed_by_user
The user closed the popup before finishing the sign in flow.
access_denied
The user denied the permission to the scopes required.
immediate_failed
No user could be automatically selected without prompting the consent flow. Error raised when using signIn with prompt: 'none' option.

gapi.auth2.AuthorizeConfig

Interface that represents the different configuration parameters for the gapi.auth2.authorize method.

Properties
client_id string Required. The app's client ID, found and created in the Google Developers Console.
scope string Required. The scopes to request, as a space-delimited string.
response_type string A list of space-delimited response type. Defaults to 'permission'. The possible values are:
  • id_token, to retrieve an ID Token
  • permission (or token), to retrieve an Access Token
  • code, to retrieve an Authorization Code
prompt string Forces a specific mode for the consent flow. The possible values are:
  • consent
    The authorization server prompts the user for consent before returning information to the application.
  • select_account
    The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for.
  • none
    The authorization server will not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not previously consented to the requested scopes.
    If code is requested as response type, the code returned will only be exchangeable for an access_token, not a refresh_token.
cookie_policy string The domains for which to create sign-in cookies. Either a URI, single_host_origin, or none. Defaults to single_host_origin if unspecified.
hosted_domain string The G Suite domain to which users must belong to sign in. This is susceptible to modification by clients, so be sure to verify the hosted domain property of the returned user.
login_hint string The email, or User ID, of a user to pre-select in the sign-in flow. This is susceptible to modification by the user, unless prompt: "none" is used.
include_granted_scopes boolean Whether to request an Access Token that includes all the scopes previously granted by the user to the app, or only the scopes requested in the current call. Defaults to true.

gapi.auth2.AuthorizeResponse

The response returned to the callback of the gapi.auth2.authorize method.

Properties
access_token string The Access Token granted. Only present if permission or token was specified in the response_type.
id_token string The ID Token granted. Only present if id_token was specified in the response_type.
code string The Authorization Code granted. Only present if code was specified in the response_type.
scope string The scopes granted in the Access Token. Only present if permission or token was specified in the response_type.
expires_in number The number of seconds until the Access Token expires. Only present if permission or token was specified in the response_type.
first_issued_at number The timestamp at which the user first granted the scopes requested. Only present if permission or token was specified in the response_type.
expires_at number The timestamp at which the Access Token will expire. Only present if permission or token was specified in the response_type.
error string When the request failed, this contains the error code.
error_subtype string When the request failed, this can contain additional information to the error code also returned.