Connected Apps

Connected Apps

Connected Apps lets Holaryn search and act in external mail, calendars, and files while keeping each
account, tenant, scope, resource, and consequence visible.

Manage accounts

Open Settings → Connected Apps. Each account card shows:

• the provider family and connected identity;
• the external tenant or domain;
• every granted OAuth scope;
• connection health and remaining provider rate-limit information when available;
• whether the account is the default when more than one account is connected.

Choose Make default only when that is the account Holaryn should use when a task does not name an
account. If several accounts match and none is a unique default, Holaryn asks for an explicit account
instead of guessing.

For bundled Google Workspace connectors, select the scopes in the connector card and choose
Connect another account. Read scopes are selected by default; send, share, write, and delete
scopes are separate and remain unchecked until selected. Holaryn displays the exact canonical scopes
again before offering the link to Google's consent page. To add scopes or repair an expired grant,
choose Reconnect or add scopes for the intended account. The provider's consent page is
authoritative. Return to Connected Apps afterward to inspect what was actually granted.

One-time Google OAuth operator setup

1. In Google Cloud → Google Auth Platform → Clients,
   create a Web application OAuth client.
2. Add this exact authorized redirect URI for the default local host:
   http://127.0.0.1:8765/api/settings/connected-apps/oauth/callback.
3. Enable the Gmail, Google Calendar, and Google Drive APIs and configure the consent screen/test
   users and only the scopes you intend to test.
4. Set HOLARYN_GOOGLE_OAUTH_CLIENT_ID and, when the client provides one,
   HOLARYN_GOOGLE_OAUTH_CLIENT_SECRET in the host environment.
5. If the host uses another port or an HTTPS reverse proxy, also set
   HOLARYN_GOOGLE_OAUTH_REDIRECT_URI to the exact registered callback URI. Restart Holaryn.

The client secret is environment-only and must not be written to config.json or committed. For
local development, keeping Google's app publishing status in Testing and adding the intended
Google accounts as test users avoids treating a development grant as a public production launch.
Connected Apps is enabled by default. An operator can set HOLARYN_CONNECTED_APPS_ENABLED=false and
restart the host as a no-migration rollback; stored accounts and encrypted credentials remain
untouched until the feature is re-enabled or explicitly revoked.

Reads and writes

Search results name their connector, account, tenant, resource type, provider identity, and
version. Results are treated as untrusted external data and fetched lazily. When more results are
available, Holaryn keeps a separate continuation cursor for each selected account so one provider or
tenant cannot redirect another account's pagination.

Sending, sharing, uploading, changing, deleting, or administering shows an approval with:

• the selected account and tenant;
• exact recipients or resource;
• exact content or permission;
• consequence (write, send, share, delete, or admin);
• required scopes and idempotency identity.

Changing any recipient, content, or permission after preview invalidates that approval.
Reusing an idempotency key with different recipients, content, permissions, account, or action is
also rejected.

Example prompt:

Search my Work Gmail for the latest launch checklist. Draft a reply to
ada@example.com summarizing the blockers, but do not send it.

A result may look like:

Found “Launch checklist” in Gmail (Work Gmail, example.com). I created a draft preview addressed
to ada@example.com. Consequence: write; scope: mail.draft. Approve to create the draft. Nothing
will be sent.

Revoke an account

On the account card, type the exact displayed phrase REVOKE <account-id> and choose
Revoke account. Holaryn asks the provider to revoke the grant, permanently deletes its encrypted
credential, stops subscriptions, clears scopes, and invalidates pending action previews.

If revocation reports a provider error, the account is not presented as fully revoked. Retry after
restoring connectivity or revoke it from the provider's own account-security page, then reconnect.

Activity and privacy

The activity table records connector/account/tenant, operation, resource identity, scopes,
consequence, and result. It does not contain OAuth token values or external resource content.
Credential values remain behind encrypted scoped-secret references and are never sent to the
model, settings API, event stream, or logs.

Troubleshooting

• Incremental consent required: reconnect the same account and approve only the displayed new
  scope.
• Several accounts match: name the account in the task or make one the default.
• Reauthorization required: the provider expired or revoked the grant; reconnect it.
• Rate limited: wait for the reported retry period; Holaryn preserves the operation's
  idempotency key.
• Repeated webhook or message: Holaryn deduplicates provider event IDs. A repeated ID with
  different content is rejected and appears as an error.
• Connect button disabled: configure HOLARYN_GOOGLE_OAUTH_CLIENT_ID, verify the exact redirect
  URI, and restart the host.