---
name: google-drive-oauth-app
description: The Google Drive API layer on top of the shared `google-cloud-console-oauth` skill — which Drive scopes are restricted and which are not, the `drive.file` per-file escape hatch and what it cannot do, the permitted-application-type rule that gates restricted Drive scopes regardless of paperwork, the verification exemptions, shared-drive access, and the Search Console domain-ownership problem for a customer bringing their own Google app. Use when asked to get Google Drive OAuth credentials, register or scope a Google Drive app, decide between `drive.readonly`, `drive` and `drive.file`, judge whether a Drive integration will need a CASA assessment, or explain why a Drive connection cannot see a team's files. Read `google-cloud-console-oauth` first for the console mechanics; use that skill alone when the Google product is not Drive, and the relevant product skill for Gmail, Calendar, Google Ads or another vendor's portal.
---

# Google Drive OAuth2 App Registration

Registering the client is quick. **The Drive scope decision you make while doing it can cost a funded external
security engagement and a recurring annual one, or nothing at all**, and it is close to irreversible once customers
are connected. The Drive
scopes that let an app see a user's existing files — `drive` and `drive.readonly` — are **restricted scopes**, which
means verification *plus* an annual third-party CASA security assessment. The non-sensitive alternative, `drive.file`,
needs none of that — but it only ever sees files the user explicitly hands to the app, which is a different product,
not a cheaper configuration.

That decision, and the eligibility rule behind it, is what this file is for. Everything else is shared.

## Built on: `google-cloud-console-oauth`

**Read `google-cloud-console-oauth` first, then this file.** It owns all the console mechanics, and this file does not
repeat them:

- Choosing/creating the Cloud project and organization, enabling APIs, and who may administer it.
- Configuring the app on the Google Auth Platform (Branding, Audience, Data Access, Clients) and creating a **Web
  application** client — the only type that yields a usable client secret.
- Redirect-URI rules (exact matching, HTTPS-only, propagation delay) and the platform's per-data-center callback list.
- The generic scope model: declaring every scope on Data Access, the non-sensitive / sensitive / restricted tiers, and
  the rule that the app's tier is its most sensitive scope.
- The client secret being shown and downloadable **only once at creation** (it is stored hashed), and add-then-disable
  rotation.
- `Testing` vs `In production` — including the seven-day refresh-token expiry — the unverified-app screen and the
  100-user caps, brand and scope verification, and the annual CASA assessment at assurance level **AL1 or AL2**.

If you are reading only this file, you are missing all of the above.

## Inputs to collect before you start

The base skill lists the console inputs. These are the Drive-specific ones, and they decide the cost of the project:

| Input | Notes |
| --- | --- |
| **Read-only or read-write?** | Decides `drive.readonly` vs `drive` — both restricted (§1) |
| **Can the product work with per-file access?** | The `drive.file` escape hatch. Ask **before** registering, not after (§3) |
| **What category of app is this?** | Restricted Drive scopes are limited to three application types (§2) |
| **Is there budget and a named owner for a CASA assessment?** | Blocking for restricted scopes |
| **Consumer accounts, a single Workspace customer, or a multi-tenant connector?** | Decides whether a verification exemption applies at all (§5) |
| **Whose domain hosts the OAuth callback?** | Must be provable in Search Console by the project's owner (§6) |
| **Do shared drives matter?** | Changes what "it can't see our files" means (§4) |

## Quick Start

1. Work the base skill's console steps, and **enable the Google Drive API** on the project — a correctly configured
   client against a project with the API disabled fails at the first API call, not at authorization.
2. Before clicking anything on Data Access, settle the scope decision: §1 (tiers), §2 (eligibility), §3 (`drive.file`).
3. If any scope is restricted, confirm the app is a permitted application type **and** that CASA is funded and owned,
   then start verification now rather than after launch.
4. Check the exemptions in §5 — one of them may remove the whole assessment.
5. Settle the callback domain and its Search Console ownership before registering redirect URIs (§6).
6. Finish the base skill's capture, round-trip and handoff steps, adding the Drive checks in §7.

## Drive platform state (verified 2026-09-20 — re-verify before trusting)

- **Drive scope tiers, from the Drive API's own scope page:** `drive`, `drive.readonly`, `drive.activity`,
  `drive.activity.readonly`, `drive.meet.readonly`, `drive.metadata`, `drive.metadata.readonly` and `drive.scripts`
  are **restricted**. `drive.apps.readonly` is **sensitive**. `drive.file`, `drive.appdata` (a.k.a. `drive.appfolder`)
  and `drive.install` are **non-sensitive**.
- **Only certain application types may use restricted Drive scopes at all**: backup-and-sync, productivity-and-
  education, and reporting-and-security. No amount of paperwork fixes an app outside those categories (§2).
- **Google actively recommends migrating to `drive.file`**, and states it works with all Drive API REST resources.
- **Restricted scopes require the annual CASA assessment** whenever the app can reach Drive data from or through a
  server — which any hosted integration does.

If the scope tables do not look like this, stop and report what you actually see.

## 1. The Drive scope tiers

| Tier | Drive scopes | What it costs |
| --- | --- | --- |
| **Non-sensitive** | `drive.file`, `drive.appdata` (a.k.a. `drive.appfolder`), `drive.install` | Basic app verification only. No security assessment. |
| **Sensitive** | `drive.apps.readonly` | Additional app verification. No security assessment. |
| **Restricted** | `drive`, `drive.readonly`, `drive.activity`, `drive.activity.readonly`, `drive.meet.readonly`, `drive.metadata`, `drive.metadata.readonly`, `drive.scripts` | Full verification **plus** an annual CASA security assessment. |

Two traps in that table:

- **`drive.metadata.readonly` is fully restricted** despite reading only metadata. "It's just filenames" is not an
  argument Google's tiering accepts, and choosing it buys the entire restricted-tier cost for a fraction of the
  capability. If metadata is all the product needs, that is an argument for `drive.file`, not for `drive.metadata.readonly`.
- **Only `drive.file` and `drive.appdata` genuinely escape the restricted tier** among the scopes that touch user
  content. `drive.appdata` is narrower still: a hidden, app-private folder the user never sees, useful for the app's
  own configuration and useless for reading the user's documents.

Drive Labels scopes sit in their own tiers: `drive.labels.readonly` and `drive.admin.labels.readonly` are
non-sensitive; `drive.labels` and `drive.admin.labels` are sensitive. A read-only label scope therefore adds nothing
to the review burden of an app that is already restricted, and does not by itself make a non-sensitive app sensitive.

## 2. Permitted application type — the gate before the paperwork

Restricted Drive scopes are not available to every app that is willing to pay for an assessment. Google limits them to
three application categories:

- **Backup and sync** — backing up or synchronizing Drive content.
- **Productivity and education** — creating, editing or collaborating on the user's files.
- **Reporting and security** — auditing, compliance or security analysis over an organization's Drive content.

**If the app is not one of these, restricted scopes are not obtainable at any price.** Check this *first*: it is the
one Drive constraint that no amount of verification effort, budget or CASA scheduling can satisfy, and discovering it
after a customer has been promised whole-Drive sync is an expensive conversation.

If the category is genuinely unclear, Google allows selecting nothing and letting its review team classify the app.
That is safer than claiming a category you cannot defend in a demonstration video.

## 3. The escape hatch: `drive.file` + the Google Picker

`drive.file` is **non-sensitive**. It avoids restricted-scope verification, the CASA assessment and the annual
re-assessment entirely, and Google states it works with all Drive API REST resources — the same calls, a narrower set
of files.

The honest trade-off, stated plainly because this is where people get misled:

- `drive.file` grants access **only to files the user explicitly picks** through the Google Picker, files a user
  shares with the app, and files the app itself created. It is per-file consent, granted one file at a time.
- **It cannot enumerate a user's Drive.** Any feature that says "sync all my files", "index the whole Drive", "watch
  for any new document", "back up everything", or "report on how files are shared across the org" is not implementable
  on `drive.file`. Those are exactly the categories Google permits restricted scopes *for* (§2).
- So this is a **product decision, not a compliance workaround** — and it is one to raise, not to take. If the
  product's value is whole-Drive visibility, `drive.file` is the wrong scope and the assessment is the price of the
  product. If the product only ever operates on documents the user hands it, `drive.file` is strictly better and
  removes the assessment and its annual renewal outright. Present both and let the owner choose.
- Switching an existing integration from restricted scopes to `drive.file` is a **re-consent event for every customer**
  plus a UI change (the Picker has to be added). It is a project. Say so rather than proposing it as a tweak.

Ask *can this work with per-file access?* **before** registering, and record the answer in the handoff. Discovering it
afterwards costs an assessment cycle.

## 4. Shared drives

Shared drives (Workspace team drives) are **not a separate scope** — the same Drive scopes cover them. Access is
governed by membership and file permissions, and shared-drive permissions are strictly expansive: a member's access
can be raised for specific files but never lowered below their shared-drive role.

Two consequences worth telling a user up front:

- An authorizing user only ever exposes shared drives **they are a member of**. "The app can't see our team drive" is
  almost always a membership problem, not a scope problem, and re-registering the client will not fix it.
- **Service accounts have no storage quota and cannot own files.** A service-account path must write into a shared
  drive or impersonate a real user, or file creation fails on quota.

## 5. Verification exemptions that can apply to a Drive app

Check these before budgeting an assessment; one of them may remove it entirely. Google lists among the cases that do
not require verification: personal use, development/testing/staging projects, apps touching only service-owned data,
**internal use within a single Workspace organization**, and **domain-wide installation**.

- **Internal to one organization.** If every user is in the owner's own Workspace org, the `Internal` audience applies
  and restricted Drive scopes need no Google review. This is a real exemption and a real limitation — a multi-tenant
  connector's users are by definition not all in one org, so it is available to a customer registering their own app
  and not to a vendor registering one for everybody.
- **Domain-wide installation.** An app installed and allowlisted by a Workspace super administrator, rather than
  consented to by individual users, is a genuinely different posture from a public consumer app, and Google lists it
  as an exception to verification. **What it does to the CASA requirement is not spelled out in Google's published
  wording.** Do not promise anyone that domain-wide installation removes the security assessment — confirm the current
  exception text at the source, and if it still does not say, treat the assessment as required and ask Google.

Neither exemption changes §2: an app outside the three permitted application types still cannot use restricted Drive
scopes.

## 6. The callback domain and Search Console ownership

Brand verification requires proving ownership of the app's authorized domains in Google Search Console, from an
account that is an Owner or Editor on the Cloud project. For Drive this lands hardest on a specific case:

**A customer bringing their own Google app cannot verify a vendor's domain.** They do not control it, cannot add the
Search Console verification record, and so cannot complete brand verification for a callback hosted on it. There is no
console setting that works around this.

> **Product fact — as of 2026-09-20**, Unified.to's Google Drive connector is flagged as requiring a **custom API
> domain (CNAME)** for its OAuth callback, precisely because of this rule. A customer registering their own Google
> client is expected to point a domain *they* control at the platform and register the callback on that host, so the
> domain they can prove in Search Console is the domain in the redirect URI. Confirm the exact hostname and the CNAME
> setup with the connector's owner before registering anything.

Settle this before adding redirect URIs — changing the callback host later means re-registering URIs and re-running
brand verification.

## Product fact — what the Drive connector asks for

> **As of 2026-09-20, Unified.to's Google Drive connector requests:**
>
> - **Read:** `openid`, `profile`, `email`, `https://www.googleapis.com/auth/drive.readonly`,
>   `https://www.googleapis.com/auth/drive.labels.readonly`
> - **Write:** `openid`, `profile`, `email`, `https://www.googleapis.com/auth/drive`,
>   `https://www.googleapis.com/auth/drive.labels.readonly`
> - **Login/identity only:** `openid`, `profile`, `email`
>
> `drive.readonly` and `drive` are both **restricted**; `drive.labels.readonly` is non-sensitive and adds nothing to
> the tier. So both the read and the write configurations put the registering app squarely in the restricted tier —
> verification *and* an annual CASA assessment. Only the login-only configuration stays non-sensitive.
>
> The connector does **not** currently offer a `drive.file` variant, so the §3 escape hatch is not available without a
> change on the connector side. It does support a **Google service-account credential** path as an alternative to the
> user OAuth flow — the domain-wide route in §5.
>
> Scope sets change. This note is dated, not live; confirm with the connector's owner before submitting anything.

## 7. Drive-specific end-to-end checks

On top of the base skill's authorize → refresh round trip:

1. Make one real Drive read (list files) and confirm the Drive API is enabled on the project and returns data.
2. Inspect the granted `scope` in the token response against what was requested — a granular-consent screen lets the
   user drop scopes, and a partially granted Drive scope set fails later with `insufficientPermissions`, not at
   consent.
3. If shared drives matter, test against a file **in a shared drive**, not just My Drive, with a user who is a member.
4. If the app uses `drive.file`, confirm a file picked through the Picker is readable **and** that a file that was
   never picked is not — that asymmetry is the whole scope, and it is easy to test against a file the app itself
   created and conclude wrongly.

| Symptom | Cause |
| --- | --- |
| Every Drive call fails although scopes look right | Google Drive API not enabled on the project |
| Auth succeeds, Drive calls 403 with `insufficientPermissions` | Granted scopes narrower than requested, or a `drive.file` app touching a file the user never picked (§3) |
| App can see My Drive but not the team's files | Shared-drive membership, not a scope problem (§4) |
| Service-account writes fail on quota | Service accounts cannot own files — write into a shared drive or impersonate a user (§4) |
| Restricted-scope request rejected despite complete paperwork | App is not a permitted application type for restricted Drive scopes (§2) |
| `403` with `rateLimitExceeded` / `userRateLimitExceeded` | Drive quota, not authorization — back off rather than re-authorizing |

## Stop and ask

Beyond the base skill's list, hand back to a human when:

- The product needs whole-Drive access and nobody has confirmed **budget and a named owner for the CASA assessment** —
  register nothing until that is answered.
- The app may not qualify as a **permitted application type** for restricted Drive scopes (§2). That is a product
  classification, not a console choice.
- Someone proposes migrating live connections between restricted scopes and `drive.file` — that re-consents every
  customer and changes the product's UI (§3).
- Search Console **domain ownership cannot be proven** for the callback domain — decide the CNAME / custom-domain
  story with the platform owner first (§6).
- Anyone wants to rely on the **domain-wide installation** exemption to skip the security assessment (§5).
- The Drive scope tiers do not match the **Drive platform state** section above.

## References

Drive-specific only; the base skill carries the generic Google OAuth references. Verified to resolve on 2026-09-20.

- Choose Google Drive API scopes (tiers, restricted-scope application types, `drive.file` guidance) — https://developers.google.com/workspace/drive/api/guides/api-specific-auth
- Google Picker overview (the `drive.file` companion) — https://developers.google.com/workspace/drive/picker/guides/overview
- Shared drives overview — https://developers.google.com/workspace/drive/api/guides/about-shareddrives
- Shared drive vs My Drive differences — https://developers.google.com/workspace/drive/api/guides/shared-drives-diffs
- Share files, folders and drives (permissions model) — https://developers.google.com/workspace/drive/api/guides/manage-sharing
- Drive Labels API authorization (label scope tiers) — https://developers.google.com/workspace/drive/labels/guides/authorize