Using Endpoints in a JavaScript Client

This page describes how to call a backend API from a JavaScript app.

To use a Cloud Endpoints API, use the Google JavaScript client library. The code you need to add to use Endpoints is minimal, as shown in the following sections.

Enabling a JavaScript client for an Endpoints API

To enable a JavaScript client to use an Endpoints API:

  1. Add the script that includes the Google-hosted JavaScript client library to your HTML:

    <script src="">
  2. Notice that the JavaScript line above includes an onload property specifying the function to be used as a callback after the library loads. Replace init with the name of your page initialization function if you did not name it init.

  3. Inside your callback function, load your Endpoint, for example:

    gapi.client.load('helloworld', 'v1', callback, apiRoot);

    This example loads helloworld v1 in the JavaScript client library and calls callback once the API is loaded.

  4. Replace apiRoot in the above code with the root URL of your API (for example, to load your own APIs. Replace helloworld and v1 with the name and version of your API backend.

Calling an Endpoints API

Once the JavaScript client is enabled for an API, you can make calls to the API using the Google JavaScript client object gapi.client. The following two calls show an insert and a list request made to the Greetings API:

Add a new greeting:

google.devrel.samples.hello.authedGreeting = function(id) {
      function(resp) {

Get the list of previous greetings:

google.devrel.samples.hello.listGreeting = function() {
      function(resp) {
        if (!resp.code) {
          resp.items = resp.items || [];
          for (var i = 0; i < resp.items.length; i++) {

During development you may want to use the Chrome developer tools JavaScript console, which automatically suggests available method names when you are manipulating gapi.client. With the above example API, typing gapi.client.tictactoe. into that console results in the Chrome developer tools suggesting scores as a possible completion.

Adding authentication support with OAuth 2.0

Built-in support for OAuth is provided by the JavaScript client library for use with Google APIs and Cloud Endpoints APIs.

Authorization is provided by the built-in authorize method. When you want to require a user sign-in, you call the following:

google.devrel.samples.hello.signin = function(mode, callback) {
  gapi.auth.authorize({client_id: google.devrel.samples.hello.CLIENT_ID,
      scope: google.devrel.samples.hello.SCOPES, immediate: mode},


  • SCOPES are the list of OAuth 2.0 scopes that must be granted to tokens sent to your backend. At minimum, you should request access to the scope: which grants access to the user’s email address.

  • mode is either false or true, depending on whether or not you’d like to present the explicit authorization window to the user. If the user has never authorized your application before, calling authorize with mode: true (no authorization window) will fail. The correct situation to use each modes is described below.

  • callback is the callback function to call once authorize completes.

Sample auth flow for a JavaScript client

Here’s an example flow for authorizing a user in a page using the JS client:

google.devrel.samples.hello.init = function(apiRoot) {
  // Loads the OAuth and helloworld APIs asynchronously, and triggers login
  // when they have completed.
  var apisToLoad;
  var callback = function() {
    if (--apisToLoad == 0) {

  apisToLoad = 2; // must match number of calls to gapi.client.load()
  gapi.client.load('helloworld', 'v1', callback, apiRoot);
  gapi.client.load('oauth2', 'v2', callback);
google.devrel.samples.hello.signin = function(mode, callback) {
  gapi.auth.authorize({client_id: google.devrel.samples.hello.CLIENT_ID,
      scope: google.devrel.samples.hello.SCOPES, immediate: mode},
google.devrel.samples.hello.userAuthed = function() {
  var request = gapi.client.oauth2.userinfo.get().execute(function(resp) {
    if (!resp.code) {
      google.devrel.samples.hello.signedIn = true;
      document.getElementById('signinButton').innerHTML = 'Sign out';
      document.getElementById('authedGreeting').disabled = false;

Note that the code sample assumes init() to be the callback function you provided when loading the JS client library. Inside init(), your API and the OAuth 2.0 API are loaded. After the OAuth 2.0 API is loaded, the sample attempts to authorize the user using immediate mode (no authorization prompt). If immediate mode succeeds, the sample sets the token for future requests to the ID token required by your Endpoint's backend.

If your user has previously authorized your application, the user is signed in, and your application can proceed normally. Authorization headers are automatically supplied with any requests.

If the user has not authorized your application previously (or there is no signed in user in the browser session), you’ll need to call authorize again, without using immediate mode. Because this method triggers a popup, it must be called as a result of a user action in the browser, such as clicking a link or button:

<a href="#" onclick="auth();" id="signinButton">Sign in!</a>

function auth() {
  signin(false, userAuthed);

Signing out

There is no concept of signing out using the JS client library, but you can emulate the behavior if you wish by any of these methods:

  • Resetting the UI to the pre signed-in state.
  • Setting any signed-in variables in your application logic to false
  • Calling gapi.auth.setToken(null);

Testing a JavaScript client against a local development server

You can test your client against a backend API running in production App Engine at any time without making any changes. However, to test your client against a backend API running on the local development server, you must change the JavaScript origin in the backend API's web client ID.

To make these required changes:

  1. Change the JavaScript origins in the credentials page for your project.
    Create client ID.

  2. Click Web application.

  3. Use the default name or supply a new one.

  4. Change the Authorized JavaScript origins field to http://localhost:8080.
  5. Click Create.
  6. Start the local development server, as described in Running and testing API backends locally.

    Make sure you don't change the default port, which is 8080, because this is what you used to set the authorized JavaScript origins previously. (You can change the port if you wish, so long as the authorized JavaScript origins and the local dev server are both set to the same port.)

  7. Test your client as desired.

Sample source code

For a sample backend API and JavaScript client that illustrates the concepts described above, see the Hello Endpoints sample.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.