Gmail

Communication

Access Gmail emails and send messages

Google developer console OAuth setup guide API docs

Installing Gmail creates a resource for the upstream API and the OAuth provider Keycard needs to mint tokens for it. Your app calls Keycard’s token exchange, gets back a token scoped to Gmail, and uses it to call the API directly. Every exchange is governed by your zone’s identity provider, access policies, and audit log - the OAuth client secret stays inside Keycard.

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/

Install

INSTALL

Add Gmail to your zone so your app can exchange tokens for it.

Step 1 - Start the install in Keycard Console

In your zone’s Keycard Console, go to Resources -> Explore Resources.
Search for Gmail and click into the catalog entry.
The install dialog shows a Redirect URI. Copy it - you’ll paste it into Gmail in Step 2. Leave this Keycard tab open.

Step 2 - Create the OAuth app for Gmail

Create a Google Cloud project

Go to the Google Cloud Console
Click Select a project → New Project
Enter a name and click Create

Go to APIs & Services → OAuth consent screen
Select External user type (or Internal if using Google Workspace)
Fill in the app name, user support email, and developer contact
Add the Gmail scopes: gmail.readonly, gmail.send
Add test users if the app is in “Testing” status

Create OAuth credentials

Go to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application
Under Authorized JavaScript origins, add http://localhost:3000
Add the Keycard-provided redirect URI under Authorized redirect URIs
Click Create and note the Client ID and Client Secret

Enable the Gmail API

Navigate to APIs & Services → Library
Search for “Gmail API”
Click Enable

Step 3 - Finish the install in Keycard Console

Switch back to the Keycard install dialog you left open in Step 1.
Paste the Client ID and Client Secret from Step 2.
Click Add Gmail. The resource is provisioned and your app can start exchanging tokens for it.

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.

Python
TypeScript

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}"},
)

import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";

const client = new TokenExchangeClient("https://<zone-id>.keycard.cloud", {
  clientId: "<your-client-id>",
  clientSecret: "<your-client-secret>",
});

const response = await client.exchangeToken({
  subjectToken: userAccessToken,
  resource: "https://gmail.googleapis.com",
});

// Call Gmail directly with the exchanged token.
const res = await fetch("https://gmail.googleapis.com/<endpoint>", {
  headers: { Authorization: `Bearer ${response.accessToken}` },
});

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

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.

Next steps

NEXT STEPS

What to do once Gmail is installed.

Now do this

Call Gmail from your code - see the Use Gmail from your code section above for Python and TypeScript samples.

Recommended

Decide who can use it - write access policies scoped to the Gmail resource so only the right users and apps reach the API.
Watch the calls - every token exchange and downstream call lands in your audit log with user identity, resource, and policy decision.