OAuth 2.1 implementation guide

This guide outlines how to securely authorize the Connected apps platform to access your services. For Connected apps MCP integrations, we highly recommend using OAuth 2.1, the industry standard for delegated authorization, with Proof Key for Code Exchange (PKCE) to ensure the highest security for user data and reliability in "agentic" flows. The Connected apps platform supports the authorization code grant type with Proof Key for Code Exchange (PKCE) parameters.

PKCE is mandatory for all OAuth 2.1 and optional for OAuth2.0.

To enable automatic discovery and streamline the onboarding process, your authorization server must support the Authorization Server Metadata extension, also referred to as OAuth Discovery.

Tip: To avoid a frustrating user experience and the need to re-link accounts, the single most important detail is to manage Refresh Token lifetime using Persistent Linking.

How Gemini MCP fetches the configuration JSON

Gemini MCP console attempts to fetch your configuration JSON from the following URLs, in the order shown in this section.

Caution: Gemini MCP console uses the first URL that returns a response—including an error.. Ensure your preferred endpoint is reachable and returns HTTP 200.

If your authorization server URL lives at the top level of your domain (for example, https://auth.example.com), Gemini appends standard "well-known" directories to your domain and looks for the server in the following order:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

If your authorization server URL lives inside a specific subdirectory or path on your domain, for example, https://auth.example.com/realms/master, Gemini appends the same "well-known" paths directly to that subdirectory, in the following order.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (nested path support)

Required JSON capabilities

Your metadata response must include the following fields. The integration fails if mandatory fields are missing or valid types aren't found.

authorization_endpoint

Must be a valid string URL.

token_endpoint

Must be a valid string URL.

response_types_supported

Must contain the string code.

registration_endpoint

For now, Play Console relies on Dynamic Client.

Registration (RFC 7591). You must provide a registration endpoint in your metadata, or input client id/secret directly in the Play Console UI.

If your authorization server doesn't support Dynamic Client Registration (DCR), you must manually implement and populate the Client ID and Client Secret fields within the Play Console UI to complete the integration.

If your implementation supports Proof Key for Code Exchange (PKCE) or persistent sessions, you must include the relevant capability fields (such as Challenge Methods and Grant Types) in your discovery JSON. This helps to ensure compatibility with Gemini's security and connectivity standards. If you support scope, you must include the scopes_supported field.

Example configuration

The following is a valid JSON response that satisfies our client's requirements.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

For cases where you include PKCE, the following snippet shows an example of what could be included in the JSON block.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

For cases where you include the scopes_supported field, the following snippet shows an example of what could be included in the JSON block.

"scopes_supported": ["mcp", "cart.order"],

Authorization code flow (simplified version)

The following steps outline the standard authorization code flow. This sequence illustrates exactly how the Connected apps platform securely obtains the necessary access tokens from your server to act on a user's behalf.

1. Authorization request: The Google surface determines it needs to call your function, but the user isn't yet authorized. The chatbot initiates the flow by redirecting the user's browser (or displaying a link) to your authorization endpoint.

   This request includes your Client ID (or autogenerated with DCR), the Gemini Redirect URI, and critical PKCE parameters (code_challenge and code_challenge_method).

   Allowlist the following URLs for the OAuth setup:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. User consent: Your authorization server validates the request, authenticates the user (login), and asks the user to grant permission for the Google surface to access their data or service.

3. Code grant: After the user consents, your server redirects the user's browser back to the Gemini RedirectURI, appending a temporary authorization code to the URL.

4. Token exchange: The backend behind Gemini sends a POST request to your token endpoint, exchanging the authorization code for an access token.

   Note: This request must include the PKCE parameter (code_verifier) to prove it is the same client that started the flow.

5. Access granted: Your token endpoint verifies the code and PKCE parameters, issues an access token and optionally a refresh token, and returns them to Gemini.

   Tip: Although refresh tokens are optional, we strongly recommend configuring your authorization server to issue them. Refresh tokens let the Connected apps platform maintain access without having to re-authenticate the user.

Key PKCE requirements

PKCE adds a layer of security to prevent the unauthorized interception of authorization codes.

Caution: Fulfilling these PKCE requirements is critical to proper management of the access and refresh tokens, which helps protect user data and maintain the integrity of the ecosystem.

• code_verifier: A cryptographically random string generated by Gemini at the start of the flow. This is kept private.
• code_challenge: A transformation of the code_verifier, usually the SHA256 hashing. This is sent publicly, as described in step 1 of the authorization code flow.
• Validation: Your token endpoint (described in step 4 of the authorization code flow) must validate that the received code_verifier, when transformed, matches the original code_challenge.

Debugging

Detailed linking error info is available in Logs Explorer, to enable and view errors follow the instructions in Monitor Account Linking errors in your Google Console project.

Google account linking configuration requirements

Read the following API guidance for information on Google account linking configuration.

• Google Account Linking with OAuth
• Your Account Linking API
• Google Account Linking API

To successfully register your OAuth integration, you need to configure specific details about your authorization server. Ensure you have the following endpoints, credentials, and assets prepared.

Configuration Field	Description	Developer Responsibility
Client ID and Secret	The unique credentials your authorization server generates specifically for the Connected apps platform. Client Secret is the secure credential (password) associated with the Client ID. Note: If the developer issued the Client ID, they must provide this. If Google issued the Client ID, the developer might need to register a secret or verify one.	Use the ID provided by the platform in all authorization requests.
Authorization Endpoint	The URL to redirect users to authenticate and grant consent	Host the endpoint—for example, https://yourdomain.com/oauth/authorize
Token Endpoint	The backend endpoint to exchange authorization codes for Access/Refresh tokens, and to refresh expired tokens.	Host this endpoint—for example, https://yourdomain.com/oauth/token
Revocation Endpoint Optional	The URL to notify your system to invalidate a token when a user disconnects. When a user unlinks or disconnects your integration from within the Connected apps platform, we will make a POST request to the /revoke endpoint containing the Access or Refresh token. See Unlinking accounts for more information.	Host the endpoint—for example, https://yourdomain.com/oauth/revoke Your server must handle this request by permanently invalidating the provided token. This ensures that any subsequent attempts by the Connected apps platform to use that token will fail, keeping the user's data secure after disconnection.
Redirect URI	The specific callback URL provided by the platform where the Authorization Server sends the code back after consent.	Configure your Authorization Server to accept only the official, registered Redirect URI from the platform.
Refresh	/token with grant_type=refresh_token A mechanism that allows the Connected apps platform to obtain a new Access Token when the current one expires, keeping the integration seamlessly connected without requiring the user to log in repeatedly. When an existing Access Token expires, the Connected apps platform will automatically make a POST request to your /token endpoint. The request payload will include grant_type=refresh_token along with the Refresh Token your server previously issued.	Your server must validate the provided Refresh Token and return a new Access Token in the JSON response. Additionally, to implement Persistent Linking, you must avoid rotating the Refresh Token during this exchange. Instead of issuing a new one, return the exact same Refresh Token in the JSON response and extend its expiration date on your backend.
Response Type	This must be configured to CODE to support the Authorization Code flow.
Scopes	The set of specific permissions and access levels that define what the token is authorized to do. These must be predefined in your configuration so Google can request them during the initial authorization handshake.	You will need to provide a list of default scopes (for example, openid, profile, email) that the Connected apps platform should request when initiating the flow. The requested scopes should be as reduced as possible (principle of least privilege) but fully sufficient for the Critical User Journeys (CUJs) your MCP integration supports.
UI Assets: Logo	Developer logo to display on the account linking and consent screens.	Must be a square vector image (SVG) with a circular appearance and at least 500 x 500 pixels. For example, see https://[partner-domain]/assets/logo.svg or the raw SVG file.
Native App linking (App Flip)	To support account linking directly from your native Android or iOS applications, relying on standard webviews is highly discouraged. Instead, implementing App Flip is strongly recommended for a seamless user experience. See Google Account Linking with OAuth-based App Flip for more information.	Complete Play Store and App Store verification, and embed Google's Redirect URIs directly into your native applications to ensure a secure, app-to-app authorization flip.
Token Lifetime	(Optional) The duration an Access Token is valid before a refresh is required. Useful for configuring timeout policies in GAL.	Common expiration times range from minutes, hours, days, depending on security needs—for example, 30 days)

Common integration errors

Here's a list of common errors and potential solutions applying to the integration process.

• Missing "code" grant: The Gemini platform's automated system explicitly checks response_types_supported for the value "code".
• Missing registration endpoint: Even if your server supports Client ID Metadata Documents, the Gemini app (acting as the OAuth client connecting to your server) currently requires a dedicated registration_endpoint to be present in the discovery JSON.
• Non-200 error: If Gemini's automated metadata discovery mechanism hits your well-known URL and receives a 404 or 500, it will not attempt to guess other URLs. Please ensure the discovery URL is publicly accessible.