Google sign-in (GAuth)

GAuth provides Google OAuth authorization, code exchange, token refresh, logout, and OIDC token verification for registered services.

Configure a project first

An APICenter operator configures GAuth for each project and environment in Management → Shared services → Google sign-in. Add the allowed application redirect URLs there and select the APICenter Google client or configure your own. Do not write directly to GAuth database tables.

The gateway uses the calling service's registered project and environment to select the configuration. A project without settings for that environment cannot start the OAuth flow. See Configure Google sign-in for the Management steps.

Get an authorization URL

The server-side SDK calls POST /api/v1/shared/gauth/oauth/authorize and returns a typed response. Redirect the user's browser to the returned URL and keep the returned state in that user's server-side session.

const authorization = await api.googleAuth.getAuthorizationUrl({
  scopes: ['openid', 'email', 'profile'],
  accessType: 'offline',
});

// Redirect the user to authorization.authorizationUrl.
// Compare the callback state with authorization.state before exchanging the code.

Exchange the authorization code

After Google redirects to an allowed URL, exchange the code with the saved state. The optional codeVerifier supports PKCE when the flow uses a code challenge.

const tokens = await api.googleAuth.exchangeCode({
  code: callback.code,
  state: authorization.state,
  // codeVerifier: session.codeVerifier,
});

The response contains the Google access token and may include a refresh token, ID token, expiry, and granted scopes. Store tokens in a protected server-side store.

Refresh or revoke tokens

if (!storedTokens.refreshToken) {
  throw new Error('No refresh token is available for this account.');
}

const refreshed = await api.googleAuth.refreshToken({
  refreshToken: storedTokens.refreshToken,
});

await api.googleAuth.logout({ token: refreshed.accessToken });

Verify an OIDC ID token

The SDK currently does not wrap token verification. Call the REST endpoint with a service bearer token:

POST /api/v1/shared/gauth/verify-token
Authorization: Bearer <service-token>
Content-Type: application/json

{"idToken":"<google-id-token>"}

The response reports whether the ID token is valid and includes verified identity claims. Do not treat an unverified token payload as identity evidence.