Authentication and Secrets

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

Agent Harness Authentication

Local mode seeds only the host Codex auth.json into a container-owned persistent Codex home. API-key mode reads the configured host environment variable. Neither mode should copy 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 dynamic client information and cached provider discovery metadata. They are encrypted in the same integration credential envelope. 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.

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.

Rotation

• 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.