Skip to content
API Reference
Admin /Catalog /API Servers
Gmail logo

Gmail

Communication

Access Gmail emails and send messages

Google developer consoleOAuth setup guideAPI docs

Adding Gmail provisions a resource (the upstream Google API at https://gmail.googleapis.com, with default scopes pre-set) and a provider for Google’s OAuth issuer - auto-provisioned on first install, or reused if you already connected another Google resource.

Your application calls Keycard’s token-exchange endpoint with the user’s identity, gets back a token scoped to this resource, and uses it to call Google directly. Identity, policy, and audit log apply to every exchange - the OAuth client secret stays inside Keycard. Each exchange is recorded in the audit log with the user identity, the resource accessed, and the policy decision.

Scopes

Section titled “Scopes”
SCOPES

OAuth permissions Keycard requests on install. Override or add scopes in Console.

https://www.googleapis.com/auth/gmail.readonly
default
https://www.googleapis.com/auth/gmail.send
default
https://www.googleapis.com/auth/gmail.labels
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.insert
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.metadata
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
https://www.googleapis.com/auth/gmail.addons.current.action.compose
https://www.googleapis.com/auth/gmail.addons.current.message.action
https://www.googleapis.com/auth/gmail.addons.current.message.metadata
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
https://mail.google.com/

Use Gmail from your code

Section titled “Use Gmail from your code”
USE FROM CODE

Call Gmail from your application with a Keycard-issued token scoped to this resource.

After installing Gmail, your application exchanges a Keycard-issued access token for a token scoped to this resource. Pass the user’s access token as the subject_token.

from keycardai.oauth import Client, BasicAuth, TokenType
import requests


# Exchange the user's Keycard token for a Gmail token.
with Client(
    "https://<zone-id>.keycard.cloud",
    auth=BasicAuth("<your-client-id>", "<your-client-secret>"),
) as client:
    response = client.exchange_token(
        subject_token=user_access_token,
        subject_token_type=TokenType.ACCESS_TOKEN,
        resource="https://gmail.googleapis.com",
    )


# Call Gmail directly with the exchanged token.
r = requests.get(
    "https://gmail.googleapis.com/<endpoint>",
    headers={"Authorization": f"Bearer {response.access_token}"},
)

See the OAuth SDK → Token Exchange reference for the full client API.

Setup

Section titled “Setup”
SETUP

Register your OAuth credentials with Keycard so the resource can issue tokens.

Create a Google Cloud project

Section titled “Create a Google Cloud project”
  1. Go to the Google Cloud Console
  2. Click Select a project → New Project
  3. Enter a name and click Create
Section titled “Configure the OAuth consent screen”
  1. Go to APIs & Services → OAuth consent screen
  2. Select External user type (or Internal if using Google Workspace)
  3. Fill in the app name, user support email, and developer contact
  4. Add the Gmail scopes: gmail.readonly, gmail.send
  5. Add test users if the app is in “Testing” status

Create OAuth credentials

Section titled “Create OAuth credentials”
  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Select Web application
  4. Under Authorized JavaScript origins, add http://localhost:3000
  5. Add the Keycard-provided redirect URI under Authorized redirect URIs
  6. Click Create and note the Client ID and Client Secret

Enable the Gmail API

Section titled “Enable the Gmail API”
  1. Navigate to APIs & Services → Library
  2. Search for “Gmail API”
  3. Click Enable

Register in Keycard

Section titled “Register in Keycard”
  1. Open Keycard Console → your zone → Resources
  2. Click Explore Resources
  3. Find and click Gmail in the catalog
  4. In the configuration dialog:
    • If this is your first Google resource, copy the Redirect URL and verify it’s added as an authorized redirect URI in your Google Cloud Console. Enter the Client ID and Client Secret from your OAuth credentials.
    • Review the User scopes - the defaults (gmail.readonly, gmail.send) are pre-populated
  5. Click Add Gmail API

Troubleshooting

Section titled “Troubleshooting”
TROUBLESHOOTING

Common errors when wiring Gmail into your zone.

Error 403: Access Not Configured

The Gmail API hasn’t been enabled in your Google Cloud project. Go to APIs & Services → Library and enable “Gmail API”.

Error 403: Insufficient Permission

The granted scopes don’t include the ones needed for the verification endpoint. Re-check:

  • The scopes configured in your Keycard resource
  • The scopes listed on the OAuth consent screen
  • Whether the user granted all requested scopes during consent
Error: redirect_uri_mismatch

The redirect URI in Google Cloud Console doesn’t match what Keycard sends. Copy the exact redirect URI from Keycard Console and paste it into Google’s authorized redirect URIs.

Section titled “Related”
RELATED