## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Connectors let agents use Google Workspace through a Google sign-in
that Paperclip Cloud manages for the user
> - When a user removes a Paperclip-managed Google connection, Paperclip
deletes the tokens locally, but the grant stays live at Google
> - Google's OAuth review expects that a disconnect ends the app's
access, and users expect it too
> - Google's revoke ends the user's whole grant to the shared client, so
only the Paperclip Cloud broker can decide when it is safe to revoke
> - This pull request asks the broker to revoke each removed grant,
keeps local removal unconditional, and tells the user the outcome in
plain language
> - The benefit is that removal ends Google access when no other
Paperclip connection needs it, and the user knows what to do when it did
not
## Linked Issues or Issue Description
**Subsystem affected**
Connectors: Paperclip-managed Google Workspace and the legacy
per-service Google connections (server removal, shared contracts,
connection UI).
**Problem or motivation**
Removing a Paperclip-managed Google connection or grant was local only.
The refresh token was deleted in Paperclip, but Google still listed
Paperclip as having access to the account. The docs said so ("Removal is
local for managed grants").
**Proposed solution**
On removal, send each removed grant's refresh token to the broker's
signed `POST /v1/connector/revoke`. The broker revokes at Google only
when no other live binding could share the grant. Paperclip records the
broker's outcome code and shows one of three plain messages. Local
removal never waits on, or fails because of, that call.
**Alternatives considered**
Call Google's revoke endpoint from the app. This ends the user's whole
grant to the shared client and can break their other Google connections,
so the broker owns the decision.
**Additional context**
Older brokers answer 409 `REVOCATION_NOT_AVAILABLE`. The app treats
that, a timeout, and a network error as "could not end access at Google"
and still removes the connection.
## What Changed
- `paperclip-cloud-connector.ts`: `revoke()` takes an optional
`timeoutMs`, returns the broker's `outcome` from an allowlist, and keeps
`REVOCATION_NOT_AVAILABLE` as an allowed rejection reason.
- New `tool-access/connections/google-access-removal.ts`. For a managed
Google connection, `prepare()` reads each removed grant's refresh token
and returns a `send()` step. `send()` calls the broker for each distinct
token, one after another, under one 5-second deadline. Every result and
every error (including a Paperclip Cloud client that cannot be created)
becomes an outcome code. It never rejects and never logs a token. An
unexpected error is logged with the error name only and reported as
`unexpected_error`.
- Order for removing a whole connection: read the tokens, run the whole
local teardown (grants, installs, app profile, gateway tokens, runtime
slots, catalog, OAuth state, archive the connection), call the broker,
delete the sent refresh-token secrets whatever the outcome, then delete
the remaining secrets. A failure anywhere in the teardown makes no
broker call. Order for removing one grant: read the token, commit the
revocation, call the broker, delete the grant's refresh-token secret.
`send()` owns the call and the deletion through an injected
secret-removal function.
- Owed revocations: a revoked managed Google grant whose refresh-token
secret still exists (and that nothing live uses) is sent by every later
removal, then the secret is deleted. This covers a process stop after
the teardown and before the call, with no new column. Once the secret is
deleted, nothing is sent again.
- Shared tokens: the shared (organization) sign-in writes the same
secret refs to the organization grant and the connection. So revoking an
organization grant alone neither calls the broker nor deletes the
secret, because the connection still uses that token; removing the
connection does both. The same rule applies to any refresh token still
used by another live grant or connection.
- Audit history: once the broker call settles, a
`connection.google_access_removal` audit event records `reasonCode` =
result and `providerAccess` (plus `grantId` for a single grant). If that
write fails, the removal still succeeds and the failure is logged.
- Revoke signs with the subject that consented to the grant
(`providerTenant.externalId`, saved by the managed callback from the
claim). Grants saved without it fall back to the refresh rule. Refresh
is unchanged; see Risks.
- `removal.ts` and `grants.ts`: `providerAccess: { provider, result,
outcomes }` goes to the responses and to the `tool_connection.archived`
and `tool_connection.grant_revoked` activity entries. The tool access
audit field `providerRevocation` keeps its Vercel meaning only.
- `packages/shared`: `ManagedGoogleAccessRemoval`,
`ManagedGoogleRevocationOutcome`, `ConnectionGrantRevocationResult`.
- UI: one helper, `connectionRemovalToast`, builds the removal toast
(base sentence plus the Google notice, tone and action) for Connectors,
Connections and the app page. No codes are shown.
- API: `docs/api/tool-connections.md` documents both DELETE responses
and `providerAccess`. The OpenAPI registration describes the optional
field and its four results.
- Docs: `GOOGLE-WORKSPACE.md` (order, owed revocations, decision table),
`GMAIL.md`, the Google connector memory note, and the help page on
deleting connection data.
Decision table, judged over the distinct tokens sent in this removal:
| Outcomes | `result` | User message |
| --- | --- | --- |
| Every token `revoked` | `ended` | "Paperclip's access to this Google
account was also ended at Google." |
| Any failure-type code: `provider_revocation_failed`,
`binding_not_known` (the broker had no record, so Google was not
called), `provider_revocation_disabled`, `revocation_in_progress`,
`revocation_not_available`, `broker_unavailable`, `broker_error`,
`credential_unavailable`, `unexpected_error` | `not_ended` | "Paperclip
removed the connection but couldn't end its access at Google. You can
remove Paperclip from your Google account's third-party connections." +
"Open Google account connections" |
| Only `other_connections_remain` | `other_connections_remain` | "Other
Paperclip connections still use this Google account, so Google keeps
Paperclip's access until you remove those too." |
| At least one `revoked`, the rest `other_connections_remain` |
`ended_unconfirmed` | "Paperclip's access was ended at Google. If more
than one Google account was connected here, check your Google account's
third-party connections to be sure." + "Open Google account connections"
|
Grants record no Google account identity: the managed callback saves
`externalId` (the Paperclip subject), `name` (the provider name), and
OAuth timing and scopes, and none of the 14 scopes returns an account
identifier. So the last row is always `ended_unconfirmed`. This includes
two tokens of one user and several agent grants on one Google account.
## Verification
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/google-managed-connection-removal.test.ts
src/services/tool-access
src/services/paperclip-cloud-connector-revoke.test.ts
src/services/paperclip-cloud-connector.test.ts
src/__tests__/tool-connection-removal.test.ts
src/__tests__/tool-access-service.test.ts
src/__tests__/openapi-routes.test.ts` (714 passed)
- `pnpm --filter @paperclipai/ui exec vitest run
src/features/connections/googleAccessRemoval.test.ts src/pages/apps`
(passed)
- Server test typecheck (`node server/scripts/typecheck-layers.mjs`)
passes.
- Red then green: the server tests failed on `master` sources (21), then
each review round's new tests failed on the previous head and pass now.
They cover: the order on both paths, local failure before the grant
commit making no call and the retry sending, cleanup failure after the
call making no second call, a process stop between commit and call being
sent on retry with the secret deleted after, a Paperclip Cloud client
that cannot be created, the consenting subject for an organization
grant, sequential sends under one deadline, each row of the decision
table (per-agent and same-user cases give `ended_unconfirmed`, a mixed
failure gives `not_ended`), the unexpected-error log without a token, no
token in any log call, the delete-stored-data option, and a toast test
per surface.
- Added time, measured locally with a stubbed broker that answers at
once: median 22.1 ms against 20.3 ms without the broker step (12 runs
each), about 2 ms. With a real broker, one round trip per removed token,
capped at 5 seconds in total.
- `pnpm verify` exits 2 (a global CI input changed), so required CI
supplies the broad coverage.
- Not verified against a live broker or a real Google account.
## Risks
- A removal of a managed Google connection or grant can take up to 5
seconds longer when the broker is slow.
- Refresh subject is not changed in this PR. In the broker
(`recordProviderGrant`), a ledger row's subject is fixed when the row is
first written, and a refresh under another subject leaves that row
untouched. So moving refresh to a new subject could stop updating the
row's last-seen time. After 200 days the row would then count as not
live, and a later removal elsewhere could revoke at Google while this
connection still works. That risk cannot be ruled out from code for rows
written before this release, so both refresh paths keep their old rules.
The two refresh paths already use different subject orders today: the
gateway prefers `connectorSubjectAgentId` and then
`connectorSubjectUserId`, while background refresh prefers the grant's
own subject. That is pre-existing, and this PR leaves it unchanged.
Revoke uses the consenting subject, which matches the claim-time ledger
row. When the row was first written by a refresh under a different
subject, the broker answers `binding_not_known` and the user gets the
warning.
- Repeated removals can send an already-removed token again; the broker
returns its recorded outcome and changes nothing at Google.
- Against an older broker, users see the "could not end access at
Google" message, which is accurate.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Gmail connection
Paperclip connects to Google's hosted Gmail MCP server at
https://gmailmcp.googleapis.com/mcp/v1. Gmail authorization is separate from
Google sign-in:
- Google sign-in identifies a Paperclip ID user and requests only
openid email profile. - Gmail authorization lets that user's agents search and read mail and create
drafts. It requests only
gmail.readonlyandgmail.compose.
Do not add Gmail scopes to the Google sign-in client. The existing Paperclip
Cloud application at my.paperclip.app hosts the public Gmail OAuth callback;
Paperclip ID remains identity-only. The originating Paperclip instance remains
the durable owner of the encrypted access and refresh tokens.
Google Workspace MCP is a Developer Preview. Enroll the required Workspace organization and test accounts in Google's Developer Preview Program before relying on the service.
Deployment layout
Use a separate Google Cloud project and OAuth web client for each environment:
| Environment | Suggested project id | OAuth client name | Authorized redirect URI |
|---|---|---|---|
| Development | paperclip-gmail-dev |
Paperclip Gmail Connection Dev |
Local Paperclip Cloud origin + /v1/connector/oauth/google/callback |
| Staging | paperclip-gmail-staging |
Paperclip Gmail Connection Staging |
https://my-staging.paperclip.app/v1/connector/oauth/google/callback |
| Production | paperclip-gmail-prod |
Paperclip Gmail Connection Production |
https://my.paperclip.app/v1/connector/oauth/google/callback |
Replace the development port if the local Paperclip Cloud application uses another port. Do not register Tailscale, customer, or other self-hosted Paperclip instance URLs with Google. The browser always returns to Paperclip Cloud first; Cloud then sends an opaque, one-time claim identifier to the exact originating instance URL that was enrolled before the flow began.
Keeping projects separate is a Paperclip release policy. It prevents a development credential or consent-screen change from affecting production and keeps restricted-scope Gmail verification independent of Google sign-in.
Google Cloud setup
Repeat this procedure in development, staging, and production. Complete and test development first, then staging. Do not enable production authorization until Google verification and Paperclip Security review are complete.
1. Create the project
- Open Google Cloud project creation.
- Select the Paperclip Cloud organization and billing account.
- Create the environment-specific project from the table above.
- Limit Owner and Editor access to the smallest operator group.
- Add a monitored engineering or security contact.
- Record the project id in the private environment runbook. Do not put a client secret in the runbook or repository.
2. Enable Gmail and Gmail MCP
In APIs & Services → Library, enable:
- Gmail API:
gmail.googleapis.com - Gmail MCP API:
gmailmcp.googleapis.com
The equivalent command is:
gcloud services enable \
gmail.googleapis.com \
gmailmcp.googleapis.com \
--project=PROJECT_ID
Do not enable Drive, Docs, Sheets, Calendar, Chat, or People for the Gmail-only release.
3. Configure branding
Open Google Auth Platform → Branding. Set:
- App name:
Paperclip - User support email: a monitored support address
- Logo: the approved Paperclip logo
- Homepage: the public Paperclip product page
- Privacy policy: the public policy that describes Gmail data handling
- Terms of service: the public Paperclip terms
- Authorized domain:
paperclip.app - Developer contact: a monitored security or engineering group
The homepage, privacy policy, and terms must be live on the verified domain before production verification. The privacy policy must explain that the originating Paperclip instance stores Gmail credentials and that Paperclip Cloud performs bounded OAuth exchange, refresh, and provider-supported revocation without durable plaintext token storage.
4. Configure the audience
Open Google Auth Platform → Audience.
- Development: select External, keep the app in Testing, and add only developer test accounts.
- Staging: select External, keep the app in Testing, and add only QA, security-review, and verification accounts.
- Production: select External and move to In production only after the required restricted-scope verification and security work is complete.
Google limits an external testing app to 100 test users. For non-basic scopes, testing grants and their offline refresh tokens can expire after seven days. Treat that expiry as expected test behavior.
5. Add the exact scopes
Open Google Auth Platform → Data Access → Add or remove scopes → Manually add scopes and add only:
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
Do not add mail.google.com, gmail.modify, gmail.send, Drive, Calendar, or
profile/sign-in scopes. Gmail read and compose are restricted scopes. Public
production use therefore requires Google's restricted-scope verification and
may require an independent security assessment for server-side handling.
6. Create the OAuth client
Open Google Auth Platform → Clients → Create Client:
- Select Web application.
- Enter the environment-specific client name from the table above.
- Add exactly the matching authorized redirect URI.
- Leave Authorized JavaScript origins empty. This is a server-side flow.
- Create the client.
- Copy the client id and newly displayed secret directly into the matching deployment secret manager.
Never paste either credential into an issue, document, chat, screenshot,
committed .env, build log, or browser-visible configuration. Step 7 lists the
deployment variables that receive them.
7. Configure the Paperclip Cloud broker deployment
Set these on the existing Paperclip Cloud application that owns the redirect URI above. This is the broker half of the configuration; the originating Paperclip instance is configured separately under Configure each originating Paperclip instance.
| Variable | Development | Staging | Production |
|---|---|---|---|
CLOUD_HARNESS_CONNECTOR_GOOGLE_GMAIL_CLIENT_ID |
Dev client id | Staging client id | Production client id |
CLOUD_HARNESS_CONNECTOR_GOOGLE_GMAIL_CLIENT_SECRET_REF |
Dev secret-manager ref | Staging secret-manager ref | Production secret-manager ref |
| Fixed callback | Local Cloud origin + /v1/connector/oauth/google/callback |
https://my-staging.paperclip.app/v1/connector/oauth/google/callback |
https://my.paperclip.app/v1/connector/oauth/google/callback |
CLOUD_HARNESS_CONNECTOR_GOOGLE_ENABLED_PROFILES |
gmail.read during the first test |
Add reviewed staging profiles | Add only approved production profiles |
CLOUD_HARNESS_CONNECTOR_ENVIRONMENT |
development |
staging |
production |
The client id and secret reference must both be present before a profile can be
used. The callback is derived from Paperclip Cloud's configured customer origin
and the provider's fixed in-code path; it is not accepted from a request or an
environment override. CLOUD_HARNESS_CONNECTOR_GOOGLE_ENABLED_PROFILES is the
profile kill switch. An omitted profile is advertised as disabled and every
authorization, refresh, and revocation request for it fails closed.
Set CLOUD_HARNESS_CONNECTOR_ENVIRONMENT explicitly in every environment. Every signed
connector request declares its own environment, and the broker accepts the
request only when that value matches both this deployment's environment and the
environment recorded on the enrolled instance. That three-way match is what
makes a leaked staging instance key inert against production, so it must equal
the instance's PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT.
Paperclip Cloud derives a safe development, staging, or production fallback
from its own customer origin, but the explicit value makes environment
isolation reviewable and avoids a custom hostname being treated as development.
The value is never derived from NODE_ENV.
Connector request requirements
The Gmail authorization request must use:
- the Gmail connector client, not the Google sign-in client;
/v1/connector/oauth/google/callbackon Paperclip Cloud;response_type=code;- the two exact Gmail scopes above;
access_type=offline;prompt=consentfor every connect and explicit reconnect;- a random, short-lived, single-use state value; and
- PKCE S256.
Do not send include_granted_scopes. After token exchange, compare the granted
scope set with the two required scopes. If either is missing, leave that
personal connection grant inactive and let the user retry deliberately.
No access token, refresh token, Google authorization code, client secret, or token fragment may appear in a browser URL. The browser return from Paperclip Cloud to the originating instance contains only an opaque one-time claim id and the instance's local state.
Token custody and instance enrollment
The expected flow is:
sequenceDiagram
actor U as User browser
participant P as Originating Paperclip instance
participant C as Paperclip Cloud connector
participant G as Google OAuth
participant V as Instance encrypted vault
U->>P: Apps → Gmail → Connect
P->>C: Signed, environment-bound authorization session
C-->>U: Existing Cloud login and destination confirmation
C-->>U: Google authorization URL with state and PKCE
U->>G: Grant Gmail read and draft access
G-->>C: Authorization code at the fixed Cloud callback
C->>G: Exchange with the Gmail client secret
C-->>U: Opaque one-time claim for the enrolled instance
U->>P: Return to exact enrolled instance URL
P->>C: Signed one-time claim
C-->>P: Instance-encrypted token response
P->>V: Encrypt tokens and bind them to the chosen user or organization grant
Before an instance can create a session:
- The instance generates an Ed25519 signing key and a separate X25519 seal key. Both private keys stay local; Ed25519 authenticates requests and X25519 lets Paperclip Cloud encrypt token responses that only the instance can open.
- An instance administrator signs in to Paperclip Cloud through its existing Paperclip ID OIDC login and enrolls the instance. Enrollment is instance-global: ordinary company membership cannot start it, and the initiating administrator must complete the return callback.
- Paperclip Cloud binds the account, opaque instance id, both public keys, deployment environment, and exact allowed browser return origins.
- On authenticated private instances, the setup request supplies its verified
same-origin HTTPS address and enrollment binds it automatically. This makes a
Tailscale HTTPS setup config-free while still rejecting a bare or mismatched
Hostheader. Loopback HTTP is development-only; other plaintext origins are rejected. - Create, claim, refresh, and supported revoke requests are signed, audience-bound,
timestamped, and protected by a one-time
jtireplay cache.
Paperclip Cloud may retain instance-encrypted initial-token ciphertext for at most five minutes. It binds the first claim to a stable local redemption id and only returns the same ciphertext to that redemption id during the retry window. It deletes the ciphertext on expiry and excludes it from long-term backups. Refresh and supported revoke operations handle plaintext only in memory for one bounded request.
Removing a managed Google profile asks Paperclip Cloud to revoke the grant. Google treats revocation as client-wide for the user, so the broker revokes at Google only when no other live binding it knows of could share the grant, and otherwise reports that other connections remain. Paperclip commits the local removal first and calls the broker only after that; the answer never changes the local result. See "Removing a managed Google connection" in GOOGLE-WORKSPACE.md.
Configure each originating Paperclip instance
Generate the two long-lived instance keys once. PEM-encoded PKCS#8 keys work directly with Paperclip:
openssl genpkey -algorithm ED25519 -out paperclip-cloud-signing.pem
openssl genpkey -algorithm X25519 -out paperclip-cloud-sealing.pem
openssl pkey -in paperclip-cloud-signing.pem -pubout -out paperclip-cloud-signing.pub.pem
openssl pkey -in paperclip-cloud-sealing.pem -pubout -out paperclip-cloud-sealing.pub.pem
Keep both private files in the instance secret manager. Enroll only the public files with Paperclip Cloud, together with the instance id, the matching environment, and every exact browser return origin. Then configure the originating Paperclip deployment:
| Variable | Development | Staging | Production |
|---|---|---|---|
PAPERCLIP_CLOUD_CONNECTOR_BASE_URL |
Local Paperclip Cloud URL | https://my-staging.paperclip.app |
https://my.paperclip.app |
PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT |
development |
staging |
production |
PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID |
Enrolled development instance id | Enrolled staging instance id | Enrolled production instance id |
PAPERCLIP_CLOUD_CONNECTOR_SIGN_PRIVATE_KEY |
Development Ed25519 private key | Staging Ed25519 private key | Production Ed25519 private key |
PAPERCLIP_CLOUD_CONNECTOR_SEAL_PRIVATE_KEY |
Development X25519 private key | Staging X25519 private key | Production X25519 private key |
Use separate keypairs and instance enrollments across environments. The connector is unavailable unless all four identity/key variables are present. HTTP is accepted only for a loopback Paperclip Cloud URL; staging and production must use HTTPS.
Cloud-hosted stacks receive these values automatically through the existing per-stack secret-reference delivery path. Self-hosted instances normally use the Apps enrollment action instead of running the OpenSSL commands manually; it generates the keys and writes them to the ignored instance secret directory with owner-only permissions.
PAPERCLIP_ID_CONNECTOR_* values are not aliases for this protocol. Paperclip
ID used different endpoints, signing metadata, envelope purposes, and Google
client credentials. An instance with only those legacy values fails with
CONNECTOR_MIGRATION_REQUIRED. Enroll it with Paperclip Cloud and reconnect
each legacy Google grant. Cloud-hosted fleets must deliver the new enrollment
keys before they deploy a binary that enables the Cloud connector.
Paperclip access defaults
Gmail uses the same credential ownership choice as the rest of the Apps setup:
- Just me stores the Gmail credential on the connecting user's grant.
- Any human in the organization stores it on the default organization grant so a deliberately shared mailbox or Workspace account can back organization-wide use.
- The disclosure states that Gmail access can search/read mail and create drafts. Sending mail is not enabled.
- A user grant does not automatically authorize an agent. The user must also install the connection for that agent, select an access profile, and grant standing delegation before autonomous use.
- Read, search, get, and list tools may be enabled after explicit profile review.
- Draft creation and label changes require Ask first.
- Trash, spam, destructive label changes, newly discovered tools, nested execution, and any future send tool remain blocked until separately reviewed.
Broker rejection diagnostics
A rejected connector request includes its operation, HTTP status, and an
allowlisted broker reason in the server error. For example,
RETURN_ORIGIN_NOT_ENROLLED means the callback origin is not enrolled for that
instance. Compare the current page/configured origin with the instance's enrolled
origins; do not bypass origin checks or copy credentials to a different instance.
Unknown codes, malformed bodies, oversized responses, and stalled diagnostic
reads produce UNKNOWN_BROKER_ERROR. This is not proof of any specific rejection
cause. Diagnostics read at most 4 KiB within 500 ms and retain no raw response
messages, URLs, tokens, authorization state, or instance/customer identifiers.
The existing error code, status, authorization, and retry behavior are unchanged.
Verification checklist
Development
- Enable the connector only in development.
- Confirm the broker's
CLOUD_HARNESS_CONNECTOR_ENVIRONMENTand the instance'sPAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENTboth readdevelopment. A mismatch fails every signed request with an environment error before Google is ever contacted, which looks nothing like a Google misconfiguration. - Use an isolated Gmail test mailbox.
- Connect from localhost and one explicitly enrolled Tailscale HTTPS origin.
- From the board Test panel, run
list_labelsand a boundedsearch_threadsquery. - Install the reviewed profile on one test agent and repeat one read-only call in a fresh agent run.
- Create a draft through an Ask-first approval and verify no send action is exposed.
- Force access-token expiry and verify refresh changes only the originating instance's encrypted secret version.
- Revoke the grant and verify the next call fails closed.
- Confirm sanitized logs, activity, API payloads, agent context, and browser history contain no credential or authorization code.
Staging
Repeat development verification, then add negative tests for replayed state, wrong origin, wrong instance, wrong company, wrong user, wrong environment, expired claim, missing scope, inactive membership, connector outage, and the seven-day testing-token expiry.
Production
- Complete Developer Preview enrollment, restricted-scope verification, any required security assessment, and Paperclip Security review.
- Configure only the production project credentials in production secrets.
- Start with an internal allowlist and read tools.
- Enable Ask-first draft and label tools only after production telemetry is clean.
- Keep destructive and send-email capabilities blocked.
- Keep the environment-specific connector kill switch available. When it is off, new authorization and refresh fail with an actionable error and never fall back to Google sign-in or another user's grant.
Troubleshooting
| Symptom | Check |
|---|---|
redirect_uri_mismatch |
The client contains the exact environment callback, including scheme, host, port, path, and no extra slash. |
| Test user cannot consent | The account is listed under the environment project's Audience test users and is enrolled in Workspace Developer Preview. |
| Refresh fails after seven days | The external app is still in Testing. Reauthorize the test user; do not treat this as token-rotation failure. |
| One required capability is missing | Inspect the returned granted scope set. Keep the grant inactive if either exact required scope is absent. |
| Local or Tailscale return is rejected | Enroll the exact origin on Paperclip Cloud. Only loopback HTTP is allowed; Tailscale must use HTTPS. |
| Every signed request fails on environment | CLOUD_HARNESS_CONNECTOR_ENVIRONMENT, the enrollment record, and PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT must agree. |
| The managed method is unavailable | Confirm the exact profile is in CLOUD_HARNESS_CONNECTOR_GOOGLE_ENABLED_PROFILES and its client id and secret reference are configured. |
| Login starts asking for Gmail | Stop the rollout. The login and Gmail clients or route namespaces have been mixed. |
| Connector is unavailable | Keep the grant in needs_reauthorization or an actionable unavailable state. Never use a login token or another environment's client. |
Refresh reports reason=PROVIDER_REAUTHORIZATION_REQUIRED |
The provider revoked, expired, or already rotated the grant, or the grant no longer matches the profile. Paperclip marks it needs_reauthorization; the user reconnects. reason=PROVIDER_OPERATION_FAILED is a provider or Cloud outage; retry later. |