Authentication and Secrets

Oblive uses several distinct credential classes. They are not interchangeable.

Agent Harness Authentication

Local mode mounts only the host Codex auth.json into a dedicated synchronizer. That single Compose service validates the file and atomically installs a strictly newer credential generation into the container-owned persistent Codex home shared by chat and task workers. The agent containers cannot read the host file directly.

Host file changes are normally detected immediately. A configurable fallback scan runs every authSyncIntervalSeconds (60 seconds by default). This scan is a low-cost safety net; it does not run before every chat turn or task.

The synchronizer does not sign in to Codex or mint credentials. If the deployment credential is no longer valid, update the host auth.json. A failed execution requests an immediate synchronization and retries once only when a newer generation was installed and no agent item had started. Other failures are not replayed automatically. The UI reports that Codex authentication failed and asks for an administrator to update the deployment credential.

API-key mode reads the configured host environment variable and does not start the file synchronizer. Neither mode copies personal plugins, sessions, global skills, or the complete host configuration into the service container.

Agent Service Token

The backend uses agentServiceToken to authenticate trusted chat and worker control-plane calls. Use a strong local value and never expose it in frontend code, screenshots, docs, or provider setup.

The trusted runtime never forwards this token into the model environment. After claiming a task run or chat turn, the backend issues a short-lived execution capability scoped to that organization, profile, and exact execution. Agent-facing control-plane calls use that capability; organization, profile, run/chat identity, department ownership, and active-root authority are rechecked by the backend on every mutation.

Integration Credential Encryption

integrationCredentialKey encrypts organization provider credential envelopes. The plaintext credential is write-only and is decrypted only inside the provider gateway when an authorized run needs it.

Standard MCP OAuth credentials also include reusable client information and cached provider discovery metadata. They are encrypted in the same integration credential envelope. A deployment-level public client ID such as metaAdsOAuth.clientId is configuration rather than an organization secret; organization tokens remain encrypted per integration. Automatic token refresh replaces the envelope only if the credential being refreshed is still current, preventing a late refresh from restoring access after a reconnect or disconnect. Meta currently provides no refresh token in this flow. Its observed lifetime is approximately 60 days, but provider metadata is authoritative; an expired Meta token requires reconnection.

OAuth client IDs and redirect URLs are deployment configuration, not organization secrets. Google client secrets remain secrets and belong only in ignored machine-local configuration or the deployment secret store. Never paste a usable client secret into issues, documentation, chat, or source control; rotate it if that happens.

Organic X uses a deployment OAuth 2.0 client ID and encrypted organization tokens. X Ads uses a separate OAuth 1.0a consumer key and secret plus encrypted per-organization access-token pairs. The X Ads consumer secret is deployment secret material and must remain backend-only. Neither connector credential enters an agent environment or workspace.

Provider-specific callback selection is backend-owned. Meta, X, and X Ads may use their dedicated redirect variables, while other managed MCP providers retain MCP_OAUTH_REDIRECT_URI. The exact selected URI is stored in one-use state and reused for exchange. After connection, direct providers read credentials only inside the backend; the agent and its workspace never receive them.

Provider Credentials

Provider API keys and OAuth refresh credentials belong to the organization integration. They must not appear in:

• source control;
• agent prompts or skills;
• context manifests;
• task workspaces;
• general process environment;
• provider URLs;
• logs; or
• action receipts.

Local Infrastructure Credentials

PostgreSQL and Garage credentials belong only in ignored local configuration. The tracked example contains placeholders so the complete shape can be validated without committing usable secrets.

Public tunnel URLs are not secrets, but they expand the local stack’s attack surface. The local control plane has no end-user authentication gate. Use an external access policy for both frontend and backend hostnames, and never expose an unrestricted tunnel.

Rotation

• For local Codex mode, complete the host login that updates auth.json; the synchronizer installs the newer generation without restarting chat or worker containers.
• Rotate a provider credential through the Integrations screen and recheck readiness.
• Disconnect before changing an OAuth identity when provider identity continuity is enforced.
• Treat integration encryption-key rotation as a migration, not a normal provider rotation.
• Restart affected services after changing service or infrastructure credentials.