> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Drive

> Connect Google Drive so Grady can find, read and file documents — scoped to exactly the folders you share with it, and never able to delete anything.

## Why connect Google Drive

A large share of the context Gradial needs already lives in Drive. The campaign brief. The approved copy deck. The product spec. The spreadsheet listing 200 pages and what each one needs. Today that context reaches Grady by someone downloading a file and attaching it — which works, but means every request starts with a manual step, and the version attached is whatever was current when the person remembered to download it.

Connecting Drive lets Grady go and get the file itself, and put results back where the rest of the team will look for them.

***

## What Grady can do

| Capability             | Detail                                                                      |
| :--------------------- | :-------------------------------------------------------------------------- |
| Browse folders         | Navigate the folder structure that has been shared with Gradial             |
| Search content         | Find files by name and content across the shared scope                      |
| Read file metadata     | Names, types, sizes, modified dates, and folder location                    |
| Download into the task | Pull a document into the working context so Grady can read and work from it |
| Create folders         | Organize output into new folders inside the shared scope                    |
| Upload files           | File documents, reports and artifacts Gradial produced back into Drive      |

<Warning>
  **Nothing is ever deleted.** The Drive connection has no delete, move, or share operation. Grady can read, create and upload — it cannot remove or relocate your files, and it cannot change who else can see them.
</Warning>

***

## How access is scoped

This is the part worth understanding before you set it up, because it differs from how most integrations work.

Gradial connects using a **Google service account** — a distinct Google identity with its own email address. That identity starts with access to nothing. It can only reach a folder or file that someone has explicitly **shared with it**, exactly as you would share with a colleague.

That means:

* **You control scope through Drive's own sharing, not through a setting in Gradial.** Share the three folders Grady should see, and those three folders are the entire world it can reach.
* **Revoking access is instant and happens in Drive.** Un-share a folder and it becomes unreachable, with no change needed in Gradial.
* **There is no organization-wide access.** The service account is not a domain-wide delegate; it cannot enumerate or reach content nobody has shared with it.

***

## Prerequisites

* A Google Cloud project where you can create a service account
* Permission to create a service account key (JSON)
* A Google Drive user or administrator who can share folders with the service account address

***

## Set up the connection

<Steps>
  <Step title="Create a service account">
    In the Google Cloud console, create a service account dedicated to Gradial. Give it a name that makes its purpose obvious to whoever audits your Drive sharing later — `gradial-drive` rather than `svc-account-3`.

    Enable the **Google Drive API** on the project.
  </Step>

  <Step title="Create and download a JSON key">
    Generate a key for the service account and download the JSON file. Handle it as a credential — it grants whatever the service account can reach.
  </Step>

  <Step title="Choose the access level">
    Gradial connections carry exactly one scope. Pick the narrower one unless you need uploads.

    | Scope                | Grady can                                       | Choose this when                                         |
    | :------------------- | :---------------------------------------------- | :------------------------------------------------------- |
    | **Read-only**        | Browse, search, read metadata, download         | Drive is a source of briefs and reference documents      |
    | **Full (non-admin)** | The above, plus create folders and upload files | You also want Gradial to file its output back into Drive |

    Even on the full scope, deletion and sharing changes remain unreachable — Gradial never constructs those requests.
  </Step>

  <Step title="Add the integration in Gradial">
    Go to **Settings → Integrations**, find **Google Drive** under Productivity & collaboration, and select **Connect**. Provide a name, paste the service-account JSON, and choose the scope from the previous step. Save — Gradial validates the credential against Drive and reports the result immediately.
  </Step>

  <Step title="Share the folders Grady should see">
    Copy the service account's email address (it appears in the JSON as `client_email`, and ends in `.iam.gserviceaccount.com`). In Google Drive, share each folder Grady should work with to that address.

    Grant **Viewer** for read-only use, or **Editor** where you want Grady to be able to upload into that folder.
  </Step>

  <Step title="Confirm">
    Ask Grady to list what it can see in Drive. It should return exactly the folders you shared — no more. If a folder you expected is missing, it hasn't been shared with the service account address.
  </Step>
</Steps>

<Tip>
  A clean pattern: create one Drive folder called something like *Gradial* with subfolders for briefs in, deliverables out, and reference material. Share that one parent folder. Scope stays obvious, and anyone auditing later can see the whole arrangement in one place.
</Tip>

***

## Troubleshooting

| Symptom                      | Cause                                                                                | Fix                                                                       |
| :--------------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| Grady sees nothing in Drive  | No folders shared with the service account yet                                       | Share at least one folder with the `client_email` address from the JSON   |
| A specific folder is missing | That folder isn't shared, or is shared with a person rather than the service account | Share it directly with the service account address                        |
| Uploads fail but reads work  | The connection uses the read-only scope, or the folder is shared as Viewer           | Reconnect with the full scope, and share the destination folder as Editor |
| Connection rejected on save  | The JSON key is malformed, revoked, or the Drive API isn't enabled on the project    | Regenerate the key and confirm the Drive API is enabled                   |
| Requests intermittently fail | Google is rate-limiting the project                                                  | Retry; if it persists, check quota on the Cloud project                   |

***

## Who this is for

| Role                       | What this unlocks                                                                             |
| :------------------------- | :-------------------------------------------------------------------------------------------- |
| **Campaign Manager**       | Pointing Grady at the brief in Drive instead of downloading and re-attaching it               |
| **Content Ops**            | Deliverables filed back where the team already looks for them                                 |
| **Marketing Ops**          | Change lists and trackers read straight from the spreadsheet of record                        |
| **Brand / Legal Reviewer** | Copy docs and QA reports arriving in a shared folder, in a format you already review in       |
| **IT / Security**          | Scope controlled through Drive's own sharing model, with no delete capability to reason about |

***

## Availability

**Access:** Must be enabled for your organization. Contact your Gradial team to get access.