← Docs

Get Gmail OAuth Working in 5 Minutes

Build a Node.js app that authenticates a user with Gmail and displays their email address. No OAuth knowledge required.

What you'll build

A minimal Express server with one button: "Connect Gmail." When clicked, the user authenticates with Google, and your app receives their email address and API tokens. The entire app is under 50 lines of code.

Prerequisites

  • Node.js 18 or higher
  • A terminal

Step 1: Create an inbox.dog API key

Run this in your terminal:

curl -s -X POST https://inbox.dog/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "tutorial"}' | npx -y json

You'll get back something like:

{
  "client_id": "id_abc123def456...",
  "client_secret": "sk_xyz789ghi012...",
  "name": "tutorial",
  "credits": 10
}

Save both values. You'll need them in the next step.

Step 2: Create the app

Set up the project:

mkdir inbox-dog-tutorial && cd inbox-dog-tutorial
npm init -y
npm install express

Create server.js with this content:

const express = require("express");
const app = express();

const CLIENT_ID = "YOUR_CLIENT_ID";       // Replace with your client_id
const CLIENT_SECRET = "YOUR_CLIENT_SECRET"; // Replace with your client_secret
const REDIRECT_URI = "http://localhost:3000/callback";

// Home page with "Connect Gmail" button
app.get("/", (req, res) => {
  res.send(`
    <h1>inbox.dog Tutorial</h1>
    <a href="https://inbox.dog/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&scope=email">
      Connect Gmail
    </a>
  `);
});

// OAuth callback — exchange code for tokens
app.get("/callback", async (req, res) => {
  const { code } = req.query;
  if (!code) return res.send("Error: no code received");

  const response = await fetch("https://inbox.dog/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      code,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
    }),
  });

  const data = await response.json();

  if (!response.ok) {
    return res.send(`<h1>Error</h1><pre>${JSON.stringify(data, null, 2)}</pre>`);
  }

  res.send(`
    <h1>Connected!</h1>
    <p><strong>Email:</strong> ${data.email}</p>
    <p><strong>Access Token:</strong> ${data.access_token.slice(0, 20)}...</p>
    <p><strong>Refresh Token:</strong> ${data.refresh_token.slice(0, 20)}...</p>
    <p>This access token works directly with the
      <a href="https://developers.google.com/gmail/api/reference/rest">Gmail API</a>.</p>
  `);
});

app.listen(3000, () => console.log("Open http://localhost:3000"));

Step 3: Run it

node server.js
  1. Open http://localhost:3000
  2. Click "Connect Gmail"
  3. Sign in with your Google account and grant permission
  4. You'll be redirected back with your email and tokens

What just happened

  1. Your app redirected the user to inbox.dog/oauth/authorize
  2. inbox.dog redirected them to Google's consent screen
  3. After consent, Google redirected back to inbox.dog, which redirected to your /callback with a short-lived code
  4. Your app exchanged that code for an access_token and refresh_token
  5. The access_token works directly with gmail.googleapis.com for 1 hour
  6. Use the refresh_token to get a new access token when it expires (free, no credit cost)

Next steps