PlanOpticon uses a unified authentication system to connect with cloud services for fetching recordings, documents, and other content. The system is **OAuth-first**: it prefers OAuth 2.0 flows for security and token management, but falls back to API keys when OAuth is not configured.
4
5
## Auth strategy overview
6
7
PlanOpticon supports six cloud services out of the box: Google, Dropbox, Zoom, Notion, GitHub, and Microsoft. Each service uses the same authentication chain, implemented through the `OAuthManager` class. You configure credentials once (via environment variables or directly), and PlanOpticon handles token acquisition, storage, refresh, and fallback automatically.
8
9
All authentication state is managed through the `planopticon auth` CLI command, the `/auth` companion REPL command, or programmatically via the Python API.
10
11
## The auth chain
12
13
When you authenticate with a service, PlanOpticon tries the following methods in order. It stops at the first one that succeeds:
14
15
1. **Saved token** -- Checks `~/.planopticon/{service}_token.json` for a previously saved token. If the token has not expired, it is used immediately. If it has expired but a refresh token is available, PlanOpticon attempts an automatic token refresh.
16
17
2. **Client Credentials grant** (Server-to-Server) -- If an `account_id` is configured (e.g., `ZOOM_ACCOUNT_ID`), PlanOpticon attempts a client credentials grant. This is a non-interactive flow suitable for automated pipelines and server-side integrations. No browser is required.
18
19
3. **OAuth 2.0 Authorization Code with PKCE** (interactive) -- If a client ID is configured and OAuth endpoints are available, PlanOpticon initiates an interactive OAuth PKCE flow. It opens a browser to the service's authorization page, waits for you to paste the authorization code, and exchanges it for tokens. The tokens are saved for future use.
20
21
4. **API key fallback** -- If no OAuth method succeeds, PlanOpticon checks for a service-specific API key environment variable (e.g., `GITHUB_TOKEN`, `NOTION_API_KEY`). This is the simplest setup but may have reduced capabilities compared to OAuth.
22
23
If none of the four methods succeed, PlanOpticon returns an error with hints about which environment variables to set.
24
25
## Token storage
26
27
Tokens are persisted as JSON files in `~/.planopticon/`:
28
29
```
30
~/.planopticon/
31
google_token.json
32
dropbox_token.json
33
zoom_token.json
34
notion_token.json
35
github_token.json
36
microsoft_token.json
37
```
38
39
Each token file contains:
40
41
| Field | Description |
42
|-------|-------------|
43
| `access_token` | The current access token |
44
| `refresh_token` | Refresh token for automatic renewal (if provided by the service) |
45
| `expires_at` | Unix timestamp when the token expires (with a 60-second safety margin) |
46
| `client_id` | The client ID used for this token (for refresh) |
47
| `client_secret` | The client secret used (for refresh) |
48
49
The `~/.planopticon/` directory is created automatically on first use. Token files are overwritten on each successful authentication or refresh.
50
51
To remove a saved token, use `planopticon auth <service> --logout` or delete the file directly.
52
53
## Supported services
54
55
### Google
56
57
Google authentication provides access to Google Drive and Google Docs for fetching documents, recordings, and other content.
**Service account fallback:** For automated pipelines, you can use a Google service account instead of OAuth. Generate a service account key JSON file from the Google Cloud Console and set `GOOGLE_APPLICATION_CREDENTIALS` to point to it. The PlanOpticon Google Workspace connector (`planopticon gws`) uses the `gws` CLI which has its own auth flow via `gws auth login`.
89
90
### Dropbox
91
92
Dropbox authentication provides access to files stored in Dropbox.
93
94
**Environment variables:**
95
96
| Variable | Required | Description |
97
|----------|----------|-------------|
98
| `DROPBOX_APP_KEY` | For OAuth | App key from the Dropbox App Console |
1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps).
105
2. Click **Create App**.
106
3. Choose **Scoped access** and **Full Dropbox** (or **App folder** for restricted access).
107
4. Copy the App key and App secret from the **Settings** tab.
108
5. Set the environment variables:
109
110
```bash
111
export DROPBOX_APP_KEY="your-app-key"
112
export DROPBOX_APP_SECRET="your-app-secret"
113
```
114
115
**Access token shortcut:** For quick testing, you can generate an access token directly from the app's Settings page in the Dropbox App Console and set it as `DROPBOX_ACCESS_TOKEN`. This bypasses OAuth entirely but the token may have a limited lifetime.
116
117
### Zoom
118
119
Zoom authentication provides access to cloud recordings, meeting metadata, and transcripts.
120
121
**Environment variables:**
122
123
| Variable | Required | Description |
124
|----------|----------|-------------|
125
| `ZOOM_CLIENT_ID` | For OAuth | OAuth client ID from the Zoom Marketplace |
126
| `ZOOM_CLIENT_SECRET` | For OAuth | OAuth client secret |
127
| `ZOOM_ACCOUNT_ID` | For S2S | Account ID for Server-to-Server OAuth |
128
129
**Server-to-Server (recommended for automation):**
130
131
When `ZOOM_ACCOUNT_ID` is set alongside `ZOOM_CLIENT_ID` and `ZOOM_CLIENT_SECRET`, PlanOpticon uses the client credentials grant (Server-to-Server OAuth). This is non-interactive and ideal for CI/CD pipelines and scheduled jobs.
132
133
1. Go to the [Zoom Marketplace](https://marketplace.zoom.us/).
134
2. Click **Develop > Build App**.
135
3. Choose **Server-to-Server OAuth**.
136
4. Copy the Account ID, Client ID, and Client Secret.
137
5. Add the required scopes: `recording:read:admin` (or `recording:read`).
138
6. Set the environment variables:
139
140
```bash
141
export ZOOM_CLIENT_ID="your-client-id"
142
export ZOOM_CLIENT_SECRET="your-client-secret"
143
export ZOOM_ACCOUNT_ID="your-account-id"
144
```
145
146
**User-level OAuth PKCE:**
147
148
If `ZOOM_ACCOUNT_ID` is not set, PlanOpticon falls back to the interactive OAuth PKCE flow. This opens a browser window for the user to authorize access.
149
150
1. In the Zoom Marketplace, create a **General App** (or **OAuth** app).
151
2. Set the redirect URI to `urn:ietf:wg:oauth:2.0:oob` (out-of-band).
152
3. Copy the Client ID and Client Secret.
153
154
### Notion
155
156
Notion authentication provides access to pages, databases, and content in your Notion workspace.
157
158
**Environment variables:**
159
160
| Variable | Required | Description |
161
|----------|----------|-------------|
162
| `NOTION_CLIENT_ID` | For OAuth | OAuth client ID from the Notion Integrations page |
163
| `NOTION_CLIENT_SECRET` | For OAuth | OAuth client secret |
1. Go to [My Integrations](https://www.notion.so/my-integrations) in Notion.
169
2. Click **New integration**.
170
3. Select **Public integration** (required for OAuth).
171
4. Copy the OAuth Client ID and Client Secret.
172
5. Set the redirect URI.
173
6. Set the environment variables:
174
175
```bash
176
export NOTION_CLIENT_ID="your-client-id"
177
export NOTION_CLIENT_SECRET="your-client-secret"
178
```
179
180
**Internal integration (API key fallback):**
181
182
For simpler setups, create an **Internal integration** from the Notion Integrations page. Copy the integration token and set it as `NOTION_API_KEY`. You must also share the relevant Notion pages/databases with the integration.
**Microsoft 365 CLI:** The `planopticon m365` commands use the `@pnp/cli-microsoft365` npm package, which has its own authentication flow via `m365 login`. This is separate from the OAuth flow described above.
267
268
## CLI usage
269
270
### `planopticon auth`
271
272
Authenticate with a cloud service or manage saved tokens.
The `AuthConfig` dataclass defines the authentication configuration for a service. It holds OAuth endpoints, credential references, scopes, and token storage paths.
The token will be saved to `~/.planopticon/slack_token.json` and automatically refreshed on subsequent calls.
474
475
## Troubleshooting
476
477
### "No auth method available for {service}"
478
479
This means none of the four auth methods succeeded. Check that:
480
481
- The required environment variables are set and non-empty.
482
- For OAuth: both the client ID and client secret (or app key/secret) are set.
483
- For API key fallback: the correct environment variable is set.
484
485
The error message includes hints about which variables to set.
486
487
### Token refresh fails
488
489
If automatic token refresh fails, PlanOpticon falls back to the next auth method in the chain. Common causes:
490
491
- The refresh token has been revoked (e.g., you changed your password or revoked app access).
492
- The OAuth app's client secret has changed.
493
- The service requires re-authorization after a certain period.
494
495
To resolve, clear the token and re-authenticate:
496
497
```bash
498
planopticon auth google --logout
499
planopticon auth google
500
```
501
502
### OAuth PKCE flow does not open a browser
503
504
If the browser does not open automatically, PlanOpticon prints the authorization URL to the terminal. Copy and paste it into your browser manually. After authorizing, paste the authorization code back into the terminal prompt.
505
506
### "requests not installed"
507
508
The OAuth flows require the `requests` library. It is included as a dependency of PlanOpticon, but if you installed PlanOpticon in a minimal environment, install it manually:
509
510
```bash
511
pip install requests
512
```
513
514
### Permission denied on token file
515
516
PlanOpticon needs write access to `~/.planopticon/`. If the directory or token files have restrictive permissions, adjust them:
517
518
```bash
519
chmod 700 ~/.planopticon
520
chmod 600 ~/.planopticon/*_token.json
521
```
522
523
### Microsoft authentication uses the `/common` tenant
524
525
The default Microsoft OAuth configuration uses the `common` tenant endpoint (`login.microsoftonline.com/common/...`), which supports both personal Microsoft accounts and Azure AD organizational accounts. If your organization requires a specific tenant, you can create a custom `AuthConfig` with the tenant-specific URLs.