Proxy Routing

The Ephos proxy is a high-performance, globally distributed gateway that bridges the gap between your autonomous agents and your sensitive API credentials. It ensures that raw keys never touch your execution environment.

Why Proxy Execution Exists: Traditional applications receive raw credentials directly inside the runtime environment. Ephos shifts this model by routing execution through an isolated gateway where delegated identities are validated and secrets remain outside the agent context.

The Routing Flow

Every request routed through Ephos passes through a constrained execution pipeline inside the Ephos Enclave before outbound proxy execution is allowed.

  1. Identity Verification: The Gateway validates your Ephos Token and ensures the request is coming from an authorized environment.
  2. In-Memory Decryption: The Ephos Enclave derives delegated execution access using the provided Token Secret and decrypts the Phantom Key into transient isolated memory.
  3. Header Injection: Ephos automatically detects the target service and injects the decrypted key into the correct header (e.g., Bearer, x-goog-api-key).
  4. Request Scrubbing: The response is returned to your agent, ensuring no secret leakage occurs in headers or error logs.

Constrained Outbound Execution

Ephos constrains outbound execution using strict domain-level policy enforcement. Even if an agent workflow is compromised through prompt injection or tool misuse, execution remains limited to explicitly authorized external services.

Security Note: We automatically block all requests to internal IP ranges, metadata endpoints (AWS/GCP/Azure), and localhost to prevent Server-Side Request Forgery.

Execution Envelope Model

A common point of confusion is seeing a POST in your code when you're trying to perform a GET. Here is how it breaks down:

  • The Outer Envelope (POST): You always POST to Ephos because you are delivering a payload of instructions.
  • The Inner Instruction (Any Method): Inside the JSON body, you specify the actual method (GET, POST, DELETE) for the target API.
// Example: Performing a GitHub GET request fetch("https://auth.phantom-projects.com/api/vault/execute", { method: "POST", // <--- Outer Envelope (To Ephos) body: JSON.stringify({ service: "GitHub [DEV]", targetUrl: "https://api.github.com/user", method: "GET" // <--- Inner Instruction (To GitHub) }) });

Technical Note: Many modern APIs (Tavily, OpenAI, Anthropic) use POST for data retrieval/search. This allows you to send a clean JSON body for complex queries rather than using long, clunky URL parameters.

Automatic Provider Detection

Ephos simplifies integration by managing the diverse authentication requirements of modern SaaS platforms. For exact header specifications and response codes, see the API Reference.

  • Bearer Auth: Used for OpenAI, Anthropic, Stripe, and most REST APIs.
  • Custom Headers: Supports provider-specific logic like Google's x-goog-api-key or GitHub's token format.
  • OAuth 2.0: Manages token refreshing and injection for enterprise integrations.

Usage Enforcement & Plan Quotas

Ephos enforces runtime quotas and execution limits directly at the Gateway before any in-memory decryption occurs inside the Ephos Enclave.

  • Session Claims: Usage limits such as monthly proxy requests, vault capacity, and active agent connections are embedded into authenticated sessions for low-latency enforcement.
  • Fallback Validation: If session claims are unavailable or malformed, the Gateway falls back to authoritative server-side policy validation before execution proceeds.
  • Audit Synchronization: Usage metadata is continuously synchronized for billing verification and forensic audit consistency.

Graceful Quota Handling: When an organization exceeds its active proxy quota, the Gateway intercepts the call, prevents decryption, and returns a clean 403 Forbidden with a structured JSON error indicating needsUpgrade: true, allowing your agentic workflows to handle quota exhaustion gracefully.