API Reference

This technical specification outlines the direct interaction protocol for the Ephos Gateway. For higher-level conceptual guides, see the Proxy Routing documentation.

Execution Gateway Protocol

Base URL: https://auth.phantom-projects.com

1. Execution Endpoint

POST /api/vault/execute

The primary data-plane endpoint. Executes a proxied request to a third-party target. Note: You always POST the instruction packet to the gateway, regardless of the target API's method (GET, POST, etc.).

Request Authentication

Ephos supports two execution authentication models depending on your runtime security requirements and deployment architecture.

Mode A (Direct Execution Authentication)
*Free Plan

POST /api/vault/execute
X-Ephos-Token: et_live_...
X-Ephos-Secret: ps_live_...
...

Mode B (Derived Execution Authentication)
*Plus & Pro Plans

POST /api/vault/execute
X-Ephos-Token: et_live_...
X-Ephos-Derived-Key: dkey_live_...
...

Instruction Packet (JSON Body)

The JSON body defines the target API, the method, and any data to be sent.

{
  "service": "OpenAI [PROD]",
  "targetUrl": "https://api.openai.com/v1/chat/completions",
  "method": "POST",
  "body": {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "..."}]
  }
}

2. Handshake Endpoint (Salt Retrieval)

GET /api/vault/salt

Plus & Pro Plans Only

Mode B Prerequisite: Retrieves the PBKDF2 salt required for local delegated key derivation and isolated execution authentication.

Note: This request only requires your Ephos Token (Identity). The Token Secret never traverses the network during salt retrieval and is used locally to derive delegated execution credentials inside the agent runtime.

GET /api/vault/salt
X-Ephos-Token: et_live_...

Headers Specification

Header	Type	Description
`X-Ephos-Token`	String	Required. Your scoped agent identity token (`et_live_...`).
`X-Ephos-Secret`	String	Required for Mode A. Your delegated token secret (`ps_live_...`).
`X-Ephos-Derived-Key`	String	Required for Mode B (Plus & Pro). The ephemeral key derived via the Salt Handshake.
`X-Ephos-Retries`	Integer	Optional. Max retry attempts for target API failures (1-5). Default is 1.

Response Status Codes

Code	Status	Meaning
`200`	OK	Success. Target response returned.
`401`	Unauthorized	Invalid Ephos Token or signature mismatch.
`403`	Forbidden	Domain restriction violation (SSRF Blocked).
`429`	Limit Reached	Organization proxy quota exceeded.
`502`	Bad Gateway	Target service returned an error.