Detect Google Workspace vs Consumer Accounts via Admin SDK

Introduction

When building applications that integrate with Google services, knowing whether a signed‑in user belongs to a Google Workspace (formerly G Suite) domain can be critical. A Workspace account often grants access to additional APIs, enterprise‑grade security policies, and custom admin controls that are unavailable to regular consumer (gmail.com) users. Detecting this distinction early helps developers tailor user experiences, enforce licensing rules, and avoid unexpected permission errors. This article walks you through the most reliable methods for checking a Google user’s account type, from server‑side verification with the Admin SDK to client‑side token inspection, and provides practical code snippets you can adapt to any web or mobile project.

Understanding Google Workspace vs. Consumer Accounts

Google distinguishes two broad categories of accounts:

• Consumer accounts – personal Gmail addresses (e.g., [email protected]) that belong to the free Google ecosystem.
• Workspace accounts – business or education addresses managed by an organization (e.g., [email protected]) and governed by an admin console.

The key technical difference lies in the domain affiliation. Workspace users are linked to a verified domain that appears in the hd (hosted domain) claim of the ID token, while consumer accounts either lack this claim or return gmail.com. Additionally, Workspace accounts can be queried via the Admin SDK, which requires domain‑wide delegation or a service account with appropriate scopes.

Using the Google Admin SDK to Verify Account Type

The most authoritative way to confirm a user’s Workspace status is through the Admin SDK Directory API. The workflow is:

1. Obtain an OAuth 2.0 access token with the https://www.googleapis.com/auth/admin.directory.user.readonly scope.
2. Call GET https://admin.googleapis.com/admin/directory/v1/users/{userKey}, where {userKey} is the user’s primary email or unique ID.
3. Inspect the response field isAdmin and orgUnitPath. If the request succeeds, the user is definitely a Workspace member; a 404 or permission error indicates a consumer account or insufficient privileges.

Because the Admin SDK requires a service account with domain‑wide delegation, you must first:

• Create a service account in Google Cloud.
• Grant it the Admin SDK scope in the Workspace admin console.
• Impersonate the target user by adding sub to the JWT payload.

This server‑side check is immune to client manipulation and works even when the hd claim is missing or spoofed.

Client‑Side Techniques: OAuth Scopes and Token Inspection

When a full Admin SDK integration is overkill, you can still infer Workspace status on the front end:

• Hosted‑Domain (hd) parameter: Include hd=yourdomain.com in the OAuth request URL. Google will prompt the user to select an account from that domain, and the returned ID token will contain an hd claim if the user belongs to it.
• ID token claims: Decode the JWT (without verification) and look for the hd field. If present, compare it to a whitelist of allowed domains.
• Scope‑based gating: Request a Workspace‑only scope such as https://www.googleapis.com/auth/drive.readonly. A consumer account can still grant the scope, but certain APIs (e.g., Google Vault) will return 403 for non‑Workspace users, providing a secondary signal.

These methods are quick to implement but should be complemented by server‑side validation for security‑sensitive applications.

Practical Implementation in Web Apps

Below is a concise example that combines both approaches using Node.js and the Google APIs client library:

const {google} = require('googleapis');
const jwt = require('jsonwebtoken');

// 1. Verify ID token and read the hd claim
async function getUserDomain(idToken) {
  const ticket = await google.auth.verifyIdToken({
    idToken,
    audience: CLIENT_ID,
  });
  const payload = ticket.getPayload();
  return payload.hd || null; // null for consumer accounts
}

// 2. If hd is missing, fall back to Admin SDK check
async function isWorkspaceUser(email) {
  const auth = new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/admin.directory.user.readonly'],
  });
  const admin = google.admin({version: 'directory_v1', auth});
  try {
    await admin.users.get({userKey: email});
    return true; // user exists in the Workspace directory
  } catch (e) {
    return false;
  }
}

In a real‑world scenario, you would first call getUserDomain after the OAuth flow. If the result is null, invoke isWorkspaceUser on the server. This layered strategy maximizes performance (client‑side fast path) while preserving reliability (server‑side authoritative verification).

Conclusion

Determining whether a Google user belongs to a Workspace domain is essential for any application that relies on enterprise features, licensing controls, or enhanced security. By understanding the structural differences between consumer and Workspace accounts, leveraging the Admin SDK for definitive server‑side checks, and supplementing with lightweight client‑side token inspection, developers can create robust detection logic that scales across platforms. Implement the layered approach illustrated above: start with the hd claim for speed, fall back to the Admin SDK when needed, and always validate scopes for added confidence. With these tools in hand, you’ll ensure that your app delivers the right experience to the right users, while staying compliant with Google’s authentication standards.