Build Now

Google OAuth Playground — Complete Guide to Testing Scopes & Tokens (2026)

Google OAuth Playground — 2026 Guide

The Google OAuth Playground is Google's official sandbox tool for testing OAuth 2.0 authorization flows without writing a single line of backend code. This guide walks you through every feature: selecting scopes, exchanging authorization codes for tokens, making live API calls, and understanding when you need to move beyond the playground to a production-grade solution.

Start building with Unipile Open OAuth Playground
OAuth 2.0 flows explained
Token lifecycle decoded
Production path included
oauth-playground.sh
# Step 1 — Select scope in Playground UI SCOPE="https://www.googleapis.com/auth/gmail.readonly" # Step 2 — Exchange auth code for tokens curl -X POST "https://oauth2.googleapis.com/token" \ -d "code=$AUTH_CODE" \ -d "grant_type=authorization_code" # Step 3 — Call Gmail API with access_token curl -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://gmail.googleapis.com/gmail/v1/users/me/messages" # access_token expires in 1h # refresh_token expires in 24h (playground default)
Definition

What Is the Google OAuth Playground?

The Google OAuth Playground is a free, browser-based tool at developers.google.com/oauthplayground that lets developers test the full OAuth 2.0 authorization flow against any Google API without setting up a backend server, registering an app, or writing server-side code.

At its core, this tool is a visual interface for the three-legged OAuth 2.0 flow. You select which Google API scopes you want, click "Authorize APIs", complete the Google consent screen, then exchange the resulting authorization code for an access token and a refresh token. From that point, you can make authenticated API requests directly inside the browser and inspect the raw request and response payloads.

It is particularly useful for teams building on top of Gmail, Google Calendar, Google Drive, or any other Google Workspace API. Instead of debugging token flows in production, you can test everything in a safe sandbox first. The google oauth 2.0 playground supports every published Google OAuth scope and shows the exact HTTP headers and JSON payloads at each step of the flow.

No backend required
Complete the entire OAuth 2.0 flow in your browser. No server, no code, no redirect URI setup on your side.
Full request inspection
See the exact HTTP request and response at every step: authorization URL, token exchange, and API call.
Official Google tool
Maintained by Google's developer relations team. Supports all Google APIs and stays current with the latest scope definitions.
Use Cases

Why Developers Use the Google OAuth Playground

The oauth2 playground solves four specific developer problems. Understanding which one applies to you will help you get the most out of each session and know when to graduate to a production setup.

Test scope coverage before production

Before shipping your app, you need to know exactly which OAuth scope grants access to which data. The playground lets you compare gmail.readonly vs gmail.modify vs gmail.send side by side, calling the actual Gmail API and inspecting what each scope exposes. This prevents over-permissioning (requesting too many scopes, which triggers more scrutiny from Google's review team) and under-permissioning (requesting too few, which causes runtime errors for your users).

Always test with the narrowest scope first. Broaden only if the API call fails.
Debug API responses without a full OAuth flow

Setting up a complete OAuth redirect flow locally takes time: you need an HTTP server, a callback URL, session handling, and token storage. The playground bypasses all of this. You authenticate once in the browser, get your tokens, and then execute any Google API endpoint directly from the "Send the request" panel. This is particularly useful for debugging unexpected 403 errors or understanding the structure of API responses before you write the parsing logic in your application.

The "Request / Response" panel shows the full HTTP exchange, including all headers.
Onboard new developers to OAuth 2.0

The playground is one of the best learning tools available for understanding how OAuth 2.0 actually works. The step-by-step UI makes the abstract flow concrete: you see the authorization URL being constructed with your chosen scopes, you see the authorization code returned in the redirect, and you see how that code gets exchanged for an access token and a refresh token. For teams onboarding engineers who are new to OAuth, a 30-minute session in the playground replaces hours of documentation reading. See our guide on integrating Google OAuth 2.0 into your app for the full production implementation.

Enable "Use your own OAuth credentials" to make the flow identical to production.
Generate ad-hoc tokens for scripts and one-offs

Sometimes you just need a valid access token to run a one-off data migration script, test a webhook payload, or verify an API integration manually. The playground generates a working access token in under 60 seconds. Copy it, paste it into your curl command or Postman, and you are done. The caveat is that playground tokens (using Google's default credentials) expire after 24 hours for the refresh token, and the access token expires after 1 hour - so this approach is limited to short-lived scripts.

Refresh tokens from playground default credentials revoke after 24 hours. Use your own credentials to avoid this.
Walkthrough

Quick Start: Your First Playground Session in 3 Minutes

Follow these five steps to go from zero to a working API call inside the playground. No Google Cloud Console setup required for this basic flow.

1
Navigate to the OAuth Playground

Open developers.google.com/oauthplayground in your browser. You will see the main interface split into three sections: Step 1 (Select and authorize APIs), Step 2 (Exchange authorization code for tokens), and Step 3 (Configure request to API). On the right side is the OAuth 2.0 configuration panel, accessible via the gear icon. Make sure you are signed in to your Google account before proceeding.

2
Select an API and scope

In the Step 1 panel, scroll through the list of Google APIs or use the search box. Click on Gmail API v1 to expand it. Select https://www.googleapis.com/auth/gmail.readonly to start with read-only access. You can select multiple scopes from multiple APIs in one session - they will all be bundled into a single authorization request. Once you have selected your scope(s), click the blue "Authorize APIs" button.

3
Complete the Google consent screen

You will be redirected to Google's consent screen. This is the same OAuth consent screen your end users will see in your production app - the playground just uses Google's own app name instead of yours. Select your Google account, review the requested permissions, and click "Allow". Google will redirect you back to the playground with an authorization code in the URL.

4
Exchange the authorization code for tokens

You are now at Step 2. The playground has automatically captured the authorization code. Click "Exchange authorization code for tokens". The playground sends a POST request to https://oauth2.googleapis.com/token and displays both the raw request and the response. You will see your access_token (valid for 1 hour) and your refresh_token in the response panel. Note these down if you need to reuse them outside the playground.

5
Make your first API call

In Step 3, enter the Gmail API endpoint in the "Request URI" field: https://gmail.googleapis.com/gmail/v1/users/me/messages. Leave the HTTP method as GET and click "Send the request". The playground injects your access token as a Bearer header automatically. The response panel displays the JSON payload from the Gmail API - a list of message IDs from your inbox. You have just completed a full OAuth 2.0 flow in the playground.

Build Now
Scope Testing

Step-by-Step: Testing OAuth Scopes in the Google OAuth Playground

Scope selection is the single most consequential decision in your OAuth integration. Too broad and Google's review team will flag your app. Too narrow and your API calls will return 403 errors. The playground lets you test every combination before you commit. For a full reference of every Gmail scope, see our Gmail API Scopes guide.

Best practice: always start with the narrowest scope that satisfies your use case. Request gmail.readonly before testing gmail.modify. This principle of least privilege reduces your app's attack surface and simplifies Google's security review. More on the review process: Google OAuth verification guide.
Gmail scopes you can test in the playground
Scope Access Level Sensitivity Use Case
gmail.readonly Read all messages and settings Sensitive Email analytics, inbox sync
gmail.modify Read, modify labels, delete messages Restricted CRM integration, triage apps
gmail.send Send messages only Restricted Transactional sending on behalf of user
gmail.compose Create, read, update, and delete drafts Sensitive AI email assistants, draft management
gmail.labels Create, read, update, and delete labels Sensitive Label automation, organization tools
gmail.metadata Read message metadata (headers, labels) only Non-sensitive Email presence indicators, thread tracking
Google Calendar scopes

The playground works equally well for Calendar API testing. To test calendar read access, select https://www.googleapis.com/auth/calendar.readonly. For full read/write access including event creation and deletion, use https://www.googleapis.com/auth/calendar. Calendar scopes follow the same pattern: start with readonly, then escalate only if you need write operations. A common mistake is requesting the full calendar scope when you only need to read availability - this unnecessarily triggers a more invasive security review.

Adding a custom scope manually

The playground also accepts custom scope URLs that are not listed in the default menu. In the Step 1 panel, look for the "Input your own scopes" field at the bottom. Paste any valid scope URL - for example, a Google Workspace Admin SDK scope or a Google People API scope - and it will be added to the authorization request alongside any scopes you selected from the list. This is useful for testing less common Google APIs that are not prominently featured in the playground UI.

Build your Gmail integration with Unipile
Token Lifecycle

Step-by-Step: Generating Access Tokens and Refresh Tokens

The Playground's Step 2 is where the real OAuth magic happens. After you authorize, an authorization code sits in the playground waiting to be exchanged. This section explains the two tokens you get back, how to force a refresh token, and how to replicate the exchange in your production code.

access_token
Expires: 1 hour

The access token is a short-lived credential (3600 seconds by default) used as a Bearer token in the Authorization header of every API request. When it expires, the API returns a 401 error. You use the refresh token to obtain a new access token without requiring the user to re-authorize. In the playground, the "Refresh access token" button does this automatically in Step 2.

refresh_token
Valid: indefinitely (or 24h in playground)

The refresh token is a long-lived credential that lets your app obtain new access tokens without user interaction. It never expires in production (unless revoked by the user, or if the app has been inactive for 6 months). However, In the playground using Google's default credentials, refresh tokens expire after 24 hours. This is a playground-specific limitation, not a production limitation.

How to force a refresh token in the playground

By default, Google only returns a refresh token the first time a user authorizes your app. On subsequent authorizations (if the user has already consented), Google skips the refresh token. To force the playground to always return a refresh token in Step 2, click the gear icon to open OAuth 2.0 configuration, and enable both "Force prompt" and "Access type: offline". With these settings, every authorization flow returns a fresh refresh token.

Reproducing the token exchange in your production code

The playground shows you the exact POST request it sends to exchange the authorization code. You can replicate this curl command directly in your backend:

token-exchange.sh
# Exchange authorization code for tokens (production equivalent) curl -X POST "https://oauth2.googleapis.com/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "code=$AUTH_CODE" \ -d "client_id=$CLIENT_ID" \ -d "client_secret=$CLIENT_SECRET" \ -d "redirect_uri=https://developers.google.com/oauthplayground" \ -d "grant_type=authorization_code" # Response: # { # "access_token": "ya29.xxx", // Bearer token, 1h TTL # "refresh_token": "1//xxx", // Long-lived (prod) or 24h (playground) # "expires_in": 3599, // Seconds until access_token expires # "token_type": "Bearer", # "scope": "https://www.googleapis.com/auth/gmail.readonly" # }

24-hour refresh token caveat: when you use the playground's default Google credentials (the most common setup), Google limits refresh token lifetime to 24 hours. This is intentional: the playground uses a single shared OAuth client, and Google revokes tokens frequently for security reasons. If you need a refresh token that survives longer than 24 hours, enable "Use your own OAuth credentials" in the playground settings - covered in the next section.

Own Credentials

Using Your Own OAuth Credentials in the Google OAuth Playground

The default playground setup uses Google's shared developer credentials, causing the 24-hour refresh token expiry. Switching to your own OAuth Client ID solves this and makes the playground behavior identical to your production app. This is the right approach when you need to test API key vs OAuth differences or work through the full Google OAuth integration flow.

Setup steps
1
In Google Cloud Console, create or select a project, then navigate to APIs and Services > Credentials. Click "Create Credentials" > "OAuth client ID".
2
Set the application type to "Web application". Give it a name like "OAuth Playground Testing". Under "Authorized redirect URIs", add exactly: https://developers.google.com/oauthplayground. This is the specific redirect URI the playground expects.
3
Click "Create". Copy the Client ID and Client Secret from the dialog that appears.
4
In the playground, click the gear icon (top right). Check "Use your own OAuth credentials". Paste your Client ID and Client Secret into the fields. Click "Close" to save.
5
Return to Step 1, select your scopes, and click "Authorize APIs". The refresh token you receive now behaves like a production token - no 24-hour expiry.
Why this matters
Refresh tokens survive past 24 hours. Your tokens behave exactly like production tokens - valid until the user revokes access or your app is inactive for 6+ months.
Your consent screen shows your app's name. Instead of "Google OAuth Playground", users see your own app name during authorization - useful for testing the exact user experience.
Restricted scopes become testable. Some scopes (like gmail.modify) require a verified app. With your own credentials, you can test in development mode with up to 100 test users without going through full verification.
Rate limits apply to your project, not shared limits. Using Google's shared playground credentials means sharing rate limit quotas with thousands of other developers. Your own credentials get their own dedicated quota.
Exact production equivalence. The token exchange request uses the same client_id, client_secret, and redirect_uri your production backend will use. You can copy the exchange code directly into your app.
Important: the redirect URI you add in Cloud Console must be an exact match. If you add https://developers.google.com/oauthplayground/ (with trailing slash) but the playground redirects to the URL without the slash, you will get a redirect_uri_mismatch error. Add both versions if you are unsure. For a deeper look at Google's error codes, see our guide on common Google OAuth errors.
Build Now
Troubleshooting

Common Google OAuth Playground Pitfalls

These are the six errors and gotchas that trip up developers most often in the playground. Each one has a specific fix that takes less than 2 minutes to apply.

1
24-hour refresh token revocation

When using Google's default playground credentials, your refresh token becomes invalid after 24 hours. Any script or integration relying on this token will start returning 401 invalid_grant errors the next day.

Enable "Use your own OAuth credentials" in the gear menu. This makes tokens behave like production tokens with no 24-hour expiry.
2
redirect_uri_mismatch error

When using your own credentials, Google returns error=redirect_uri_mismatch during the authorization step. This means the redirect URI in your Cloud Console OAuth client does not exactly match what the playground sends.

In Cloud Console, add exactly https://developers.google.com/oauthplayground (no trailing slash) as an authorized redirect URI. See our guide on OAuth errors for more.
3
Scope not authorized (403 on API call)

The API call in Step 3 returns 403 insufficientPermissions. This happens when you call an endpoint that requires a scope you did not include in Step 1, or when you forgot to click "Authorize APIs" after adding a new scope.

Go back to Step 1, verify the correct scope is checked, then click "Authorize APIs" again. The playground resets on a new authorization - do not try to reuse the old tokens.
4
Token expired mid-test (401 after 1 hour)

Access tokens are valid for only 3600 seconds. If your testing session runs long, calls in Step 3 will start returning 401 Invalid Credentials even though your refresh token is still valid.

In Step 2, click "Refresh access token". The playground uses your refresh token to obtain a new access token in seconds without requiring re-authorization.
5
Wrong API version in the request URI

Some Google APIs have versioned scope requirements. For example, the Google Calendar API v3 uses different base URLs from older versions. Using a scope designed for v1 on a v3 endpoint may return unexpected errors or incomplete data.

Always verify the API version in the endpoint URL matches the scope you selected. Check the official Google API documentation for the current stable version of each API.
6
CORS errors in the browser console

You see CORS-related errors in DevTools when using the playground's "Send the request" feature from certain network environments (corporate proxies, VPNs). This is a playground-specific browser behavior, not a Google API issue.

Copy the request from the playground and execute it via curl from your terminal. Google APIs fully support CORS in production - this is a playground UI limitation only. The actual API call will work fine from a backend.
Comparison

Playground vs Production: When You Outgrow the Google OAuth Playground

The playground is an excellent testing tool - not designed for production use. Here is an honest comparison of what changes when you move from playground testing to a real OAuth integration serving real users.

Feature OAuth Playground Production App
Refresh token lifetime 24h max (with Google's credentials)
Unlimited with own credentials		 Unlimited until user revokes or 6-month inactivity
User base 1 user (your Google account only) N users - any number of Google accounts can authorize your app
OAuth verification Not required - playground bypasses review Required after 100 test users, for restricted scopes
CASA Tier 2 security review Not applicable - playground is Google's own tool Required for apps requesting restricted Gmail or Calendar scopes
Consent screen branding Shows "Google OAuth 2.0 Playground" as the app name Shows your app's name, logo, and privacy policy
Request / response visibility Full visibility - see every HTTP header and payload Hidden from end users - only your backend sees the raw tokens and API responses
API rate limits Standard Google API quotas (shared with other playground users when using Google's credentials) Your own project's dedicated quota - no sharing with other developers
Intended use case Testing, debugging, learning, generating one-off tokens Serving end users at scale with persistent, multi-user token management

The rule of thumb: use the playground until your integration logic is confirmed, then move to a production OAuth flow for anything user-facing. The biggest friction point in production is Google's verification process - for apps requesting sensitive or restricted scopes, this can take weeks. That is where a solution like Unipile can help: use pre-verified credentials and skip the review entirely while you are validating product-market fit. See our full guide on OAuth email API integration for a deep dive into production patterns.

Weeks of verification.
Use Unipile's key and start now.

You tested in the playground - now go production without the 6-month Google verification wait. Connect Gmail accounts in 5 minutes with our pre-verified developer credentials.

Use Unipile's Google Key
SOC 2 - GDPR - No app review needed - Switch to your own key anytime
CASA Tier 2 Certified
connect-gmail.shcurl
# No Google Cloud Console. No review.# Connect any Gmail account in 5 min. curl -X POST "https://api.unipile.com/v1/accounts" \ -H "X-API-KEY: $UNIPILE_KEY" \ -d '{ "provider": "GOOGLE_OAUTH", "use_unipile_credentials": true }'
Production Path

From Google OAuth Playground to Production: Skip the Verification Wait

The playground confirmed your integration logic works. The next step is connecting real user accounts in production. But here is the problem: Google's OAuth verification process for apps requesting sensitive or restricted Gmail scopes can take 4 to 12 weeks, and requires a CASA Tier 2 security audit for restricted scopes like gmail.modify and gmail.send.

Unipile solves this with pre-verified Google OAuth credentials. Instead of waiting months for Google to approve your app, you use Unipile's CASA Tier 2 Certified developer key to connect Gmail accounts immediately. Your users authorize through Google's standard consent screen, your app reads and sends emails via Unipile's API, and you can switch to your own verified credentials at any time when you are ready. This is the same approach used by teams building on top of our Google OAuth integration and our broader Email API platform.

No Google Cloud Console setup
Skip project creation, credential setup, and authorized redirect URI configuration for initial deployment.
CASA Tier 2 Certified
Unipile's credentials have passed Google's highest tier security assessment. SOC 2 and GDPR compliant.
Switch to your own key anytime
Start with Unipile's key to ship fast, then migrate to your own verified credentials with zero downtime.
Start building - no verification wait

Google OAuth Playground - FAQ

Answers to the most common questions about testing, tokens, scopes, and moving to production from the playground.

The Google OAuth Playground is a free, browser-based tool at developers.google.com/oauthplayground that lets developers test OAuth 2.0 authorization flows against any Google API. Select scopes, authorize your Google account, exchange the authorization code for tokens, and make live API calls - all without writing backend code. Maintained by Google, it supports every published Google API scope.

Access tokens expire after 1 hour (3600 seconds). Refresh tokens using Google's default playground credentials expire after 24 hours - this is a playground-specific limitation. If you configure the playground to use your own OAuth credentials (Client ID and Client Secret from Google Cloud Console), refresh tokens behave exactly like production tokens with no 24-hour expiry. You can also click "Refresh access token" in Step 2 at any time to get a new access token without re-authorizing.

No. The playground is a testing and debugging tool only. It is limited to one user account (your own), tokens expire quickly with default credentials, and it does not support multi-user authorization flows needed by production apps. For production, you need to register your own OAuth app, implement the authorization redirect flow in your backend, and for sensitive scopes like gmail.modify, complete Google's verification process. Alternatively, use a service like Unipile's pre-verified OAuth credentials to ship faster.

In Google Cloud Console, create an OAuth 2.0 Web application credential and add https://developers.google.com/oauthplayground as an authorized redirect URI. Copy the Client ID and Client Secret. In the playground, click the gear icon, enable "Use your own OAuth credentials", and paste your Client ID and Client Secret. Click "Close", then proceed with Step 1 scope selection and authorization as normal. Your tokens will now have production-equivalent lifetimes.

The 24-hour expiry is because you are using the playground's default shared credentials (Google's own OAuth client). Google intentionally limits these shared tokens for security reasons. This is not how production OAuth tokens work. The fix is to enable "Use your own OAuth credentials" in the playground gear settings and provide your own Client ID and Client Secret. With your own credentials, refresh tokens are valid until the user explicitly revokes access or the app is inactive for 6 months.

Yes, fully. In the playground Step 1, expand "Gmail API v1" and select any Gmail scope (gmail.readonly, gmail.modify, gmail.send, etc.). After authorization, in Step 3 enter the endpoint URL such as https://gmail.googleapis.com/gmail/v1/users/me/messages and click "Send the request". You will see the live response from your Gmail inbox. For a complete reference of Gmail scopes and their permissions, see our Gmail API Scopes guide.

The playground supports all published Google API scopes. The built-in list includes Gmail API, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Slides, Google Admin SDK, Google People API, Google Tasks, YouTube, and many others. You can also test any custom scope by entering the full scope URL manually in the "Input your own scopes" field. Multiple scopes from different APIs can be combined in a single authorization request.

This error only appears when using your own OAuth credentials. Go to Google Cloud Console, open your OAuth client's settings, and add https://developers.google.com/oauthplayground (without trailing slash) as an authorized redirect URI. Save, wait a few minutes for changes to propagate, then retry. If the error persists, also try adding the version with a trailing slash. For more OAuth error fixes, see our Google OAuth errors guide.

Yes, the Google OAuth Playground is completely free. There is no account required to use the playground interface itself - just navigate to developers.google.com/oauthplayground and sign in with any Google account. The API calls you make through the playground count against your Google Cloud project's quota (which has a generous free tier for most APIs), but the playground tool itself has no cost. For a fully managed alternative, see Unipile's production-ready Gmail API.

For SaaS applications connecting Gmail or Google Calendar accounts for multiple end users, Unipile provides a production-ready OAuth API with pre-verified Google credentials (CASA Tier 2 Certified, SOC 2, GDPR compliant). Instead of the 4-12 week Google verification process for restricted scopes, you can connect user Gmail accounts immediately. You can also read the Unipile Google OAuth documentation to see the exact API calls required. Switch to your own verified credentials at any time with no downtime.

Still have questions about Google OAuth or the playground?

Talk to an expert
en_USEN
fr_FRFR es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR en_USEN