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

# OAuth & Authentication

> How ZeroTwo uses OAuth 2.0 to connect to your apps securely — without storing your passwords.

Every ZeroTwo connector uses **OAuth 2.0**, the industry-standard protocol for delegated authorization. This means ZeroTwo can act on your behalf within connected apps without ever knowing your password.

## How OAuth 2.0 works

When you connect an app to ZeroTwo, here's what happens behind the scenes:

<Steps>
  <Step title="ZeroTwo initiates the flow">
    ZeroTwo redirects your browser to the app's official authorization server (e.g., `accounts.google.com`, `github.com/login/oauth`).
  </Step>

  <Step title="You authenticate and authorize">
    You log in to the app (if not already logged in) and review the specific permissions ZeroTwo is requesting. You click **Allow** or **Authorize** to grant access.
  </Step>

  <Step title="The app issues an access token">
    The app's authorization server generates an OAuth access token and refresh token, then redirects back to ZeroTwo with those tokens.
  </Step>

  <Step title="ZeroTwo stores the token securely">
    ZeroTwo encrypts and stores the access token and refresh token. Your password is never involved or stored at any point.
  </Step>

  <Step title="ZeroTwo uses the token on your behalf">
    When you ask ZeroTwo to interact with the connected app — via Agent Mode, @ mention, or a Task — it presents the stored access token to the app's API. The app honors the request because the token represents your authorization.
  </Step>
</Steps>

## What ZeroTwo stores

| What is stored          | Details                                                       |
| ----------------------- | ------------------------------------------------------------- |
| **OAuth access token**  | Used to make API calls to the connected app on your behalf    |
| **OAuth refresh token** | Used to obtain new access tokens when the current one expires |
| **Authorized scopes**   | The list of permissions you granted during the OAuth flow     |
| **Connection metadata** | App name, account identifier, connection date                 |

<Warning>
  ZeroTwo does **not** store your password, your app's login credentials, or any data beyond what's listed above. Tokens are encrypted at rest and never transmitted in plaintext.
</Warning>

## Automatic token refresh

OAuth access tokens have limited lifetimes — typically 1 hour for most apps. ZeroTwo automatically refreshes tokens before they expire using the stored refresh token. In practice, this means:

* You connect once and rarely need to reconnect
* The connector stays active as long as you haven't revoked access from the app's side
* If a refresh fails (e.g., you revoked access from within the app), the connector shows **"Needs reauthorization"** and you'll need to reconnect

## Scopes and permissions

Each connector requests a specific set of **OAuth scopes** — granular permissions that define exactly what ZeroTwo can do with the app. For example:

| App          | Example scopes                                                  |
| ------------ | --------------------------------------------------------------- |
| Gmail        | `gmail.readonly` (read emails), `gmail.send` (send emails)      |
| GitHub       | `repo` (read/write repos), `issues:write` (create issues)       |
| Google Drive | `drive.readonly` (read files), `drive.file` (create/edit files) |
| Notion       | `read_content`, `update_content`, `insert_content`              |

The scopes being requested are displayed on the app's authorization page **before** you approve the connection. Take a moment to review them.

### Principle of least privilege

Only grant the scopes that match what you actually plan to do. If you only need ZeroTwo to read your Google Drive files, connect with read-only scope. You can always disconnect and reconnect with broader permissions later if your needs change.

## Revoking access

You can revoke ZeroTwo's access to a connected app in two places:

**From ZeroTwo:**

1. Go to **Settings → Connectors**
2. Click the app
3. Click **Disconnect**

ZeroTwo immediately deletes the stored tokens. The app will no longer respond to requests from ZeroTwo.

**From the app itself:**

Most apps have a "third-party app access" or "authorized applications" section in their own settings. For example:

* **Google**: myaccount.google.com → Security → Third-party apps with account access
* **GitHub**: github.com → Settings → Applications → Authorized OAuth Apps
* **Notion**: notion.so → Settings → My connections

Revoking from the app's side invalidates the token. ZeroTwo will then show the connector as **"Needs reauthorization"**.

<Info>
  For complete removal, revoke from both ZeroTwo and the app. Revoking only from the app means ZeroTwo still holds the (now invalid) token until you explicitly disconnect in ZeroTwo.
</Info>

## Security properties

| Property                      | Details                                                             |
| ----------------------------- | ------------------------------------------------------------------- |
| **No password storage**       | ZeroTwo never receives or stores your app password                  |
| **Encrypted tokens**          | Access and refresh tokens are encrypted at rest                     |
| **Scoped access**             | ZeroTwo can only perform actions within the scopes you authorized   |
| **Revocable anytime**         | You can disconnect any connector instantly, from ZeroTwo or the app |
| **No cross-account access**   | Each connection is tied to your ZeroTwo account only                |
| **No plaintext transmission** | Tokens are never sent over unencrypted connections                  |

## Questions about a specific connector

For app-specific OAuth behavior, permission scopes, and what ZeroTwo can do within each app, see the individual integration documentation pages or visit **Settings → Connectors → \[app name]** for a scopes summary.