External Integrations and API Governance

Purpose of This Section

This document defines how the assistant interacts with external services through APIs while maintaining strict security, cost control, and auditability. External integrations are treated as bounded capabilities, not extensions of trust. The goal is to extract value from external services without allowing them to become covert control planes or unmonitored exfiltration paths.

Integration Philosophy

Every external integration introduces a new dependency, a new failure mode, and a new path through which data might leave the system. These costs are real even when the integration itself is well-behaved, because they compound over time and across services. An assistant with access to a dozen APIs has a dozen points at which credentials might leak, behavior might change without notice, or a provider’s policy shift might alter what data is retained on the other end.

This architecture keeps the integration surface deliberately small. Integrations are few, purpose-specific, revocable, and observable. Convenience alone is never a sufficient justification for adding a new external dependency. Each integration must serve a documented purpose that cannot be met through existing capabilities, and the operator must explicitly approve it before it is configured.

Approved Integrations

The assistant is restricted to a short, explicit allowlist of external APIs. In the current deployment, this includes a search and research provider and a secondary web discovery provider. No other external services are accessible unless the operator explicitly approves and documents them.

The allowlist is enforced rather than advisory. Any attempt to access an undeclared external service is treated as a policy violation, not an oversight. This distinction matters because a permissive integration posture — one that allows new services by default and blocks only known-bad ones — would require the operator to anticipate every possible integration in advance. A restrictive posture requires only that the operator approve integrations as they become necessary, which is a smaller and more reliable obligation.

Credential Ownership and Isolation

All API credentials are owned by the assistant’s dedicated accounts, not the operator’s. Each credential is scoped to the minimum permissions required for its purpose and is not shared across services. The assistant never uses human-owned API keys for any interaction.

This isolation ensures that credential compromise does not propagate across identities. If an API key associated with the assistant is leaked, the damage is limited to that single service under the assistant’s account. The operator’s own API keys, accounts, and billing relationships remain unaffected. Conversely, if the operator’s credentials are compromised through an unrelated incident, the assistant’s integrations continue to function under their own independent credentials.

Spending Limits as Security Controls

Each API credential is configured with strict spending limits: low monthly caps, automatic reset periods, and a hard stop on budget exhaustion. These limits are treated as security controls rather than budget optimizations. The distinction is important. A budget optimization aims to reduce cost while maintaining functionality. A security control aims to bound the damage that a compromised or misbehaving system can inflict.

If a key is leaked and an attacker uses it to make requests, the financial exposure is capped at the monthly limit. If the assistant enters a research loop and makes progressively more API calls without converging on a useful result, the spending limit halts the loop before it becomes expensive. In both cases, the limit functions as a circuit breaker — a hard boundary that does not depend on the assistant’s own judgment to enforce.

Usage Monitoring and Alerts

The assistant monitors its own API usage, tracks cost in near real time, and compares consumption against predefined thresholds. When a threshold is crossed, the operator is alerted.

Alerts are tiered to distinguish between routine events and situations that require intervention. Informational alerts mark normal usage milestones and require no action. Warning alerts indicate elevated or unusual consumption and prompt the operator to evaluate whether the usage pattern is expected. Critical alerts signal that a limit is being approached or has been exceeded and carry an expectation of immediate review.

This tiering prevents alert fatigue — a problem discussed in more detail in a later section — while ensuring that genuinely anomalous behavior reaches the operator’s attention. A system that alerts on everything teaches its operator to ignore alerts. A system that alerts only when something is meaningfully wrong earns the operator’s attention when it needs it.

No Autonomous Key Management

The assistant cannot generate new API keys, rotate credentials autonomously, or request expanded permissions from any external provider. All credential changes require human action. This constraint prevents the assistant from widening its own authority surface, whether through intentional escalation or through a well-meaning attempt to improve its own security posture by rotating keys. Credential rotation is a sound practice, but in this architecture it is the operator’s responsibility, not the assistant’s, because the act of issuing a new credential is an act of authorization.

Key Storage and Retrieval

API keys are never embedded in code, configuration files, or documentation. They are stored in a dedicated secret management system, retrieved at runtime when needed, and not retained in memory beyond immediate use. This approach minimizes the window during which a credential is exposed and ensures that backups, version-controlled configuration, and documentation remain free of secrets — a property that the backup and recovery model depends on.

Logging and Redaction

API interactions are logged at a level that supports accountability without creating a data leak vector. Logs record the timestamp, the service name, and the purpose of each request. Sensitive details — request bodies, response payloads, authentication headers — are redacted. The resulting logs answer the question “what did the assistant communicate with, when, and why” without revealing the content of those communications in a form that could be exploited if the logs themselves were accessed by an unauthorized party.

Failure Behavior

The system assumes that APIs may be unavailable, providers may change behavior without notice, and keys may be revoked or expire. When any of these conditions occurs, the assistant degrades gracefully and notifies the operator rather than attempting workarounds. It does not try alternative endpoints, fall back to undeclared services, or retry indefinitely. The correct response to an integration failure is to report it and wait for guidance, not to improvise around it.

Decommissioning Integrations

When an integration is no longer required, the associated API key is revoked, documentation is updated to reflect the change, and usage logs are archived. Decommissioning is treated as a normal lifecycle event. Integrations that are no longer needed should not persist as dormant credentials with residual access — they should be removed cleanly, just as an employee’s access badge is collected when they leave an organization.

Summary

By enforcing strict API governance, the architecture ensures minimal external dependency, bounded financial and security risk, clear observability into external interactions, and straightforward revocation and recovery. External services are tools employed for specific purposes under defined constraints. They are not partners, and they are not trusted beyond the scope of each individual interaction.

This document establishes how the assistant safely interacts with the outside world. The next section addresses tooling extensibility and third-party skill governance.