simplaix · penghanyuan · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
@@ -6,11 +6,14 @@ An open-source Agent Gateway that gives your AI agents a secure foundation — i
 
 AI agents are increasingly autonomous — they call APIs, access sensitive data, and take real-world actions on behalf of users. But most agent frameworks lack the infrastructure to do this safely:
 
-- **Who is this agent?** No standard identity or authentication model.
-- **What can it access?** No fine-grained access control for tools and APIs.
-- **Where are the credentials?** Secrets are hardcoded or scattered across configs.
-- **Did anyone approve this?** No human-in-the-loop for high-risk operations.
-- **What happened?** No audit trail when things go wrong.
+Simplaix Gateway is the infrastructure layer that answers all of these questions.
+
+| Question | The gap |
+|----------|---------|
+| **Who is this agent?** | Agents have no standard identity or authentication model. Any request claiming to be an agent is trusted implicitly. |
+| **What is it allowed to do?** | There is no fine-grained access control over which tools and APIs an agent can invoke on behalf of which user. |
+| **Did anyone approve this?** | High-risk operations — deleting data, sending messages, moving money — execute silently with no human checkpoint. |
+| **What actually happened?** | When something goes wrong, there is no structured record of ***who asked which agent to do what, and when***. |
 
 Simplaix Gateway sits between your agents and the outside world, solving all of these problems in one layer.
 

@@ -1,11 +1,32 @@
 ---
 title: Agents
-description: CRUD operations for managing agents, including invocation and credential pre-checks.
+description: Admin agent management, runtime token lifecycle, and agent invoke APIs.
 ---
 
-All agent management endpoints require JWT authentication.
+## Endpoint Map
 
-## Register Agent
+### Admin Management (`/api/v1/admin/agents`)
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/api/v1/admin/agents` | JWT + `agent:create` | Create agent and return one-time runtime token |
+| `GET` | `/api/v1/admin/agents` | JWT + `agent:read` | List agents |
+| `GET` | `/api/v1/admin/agents/:id` | JWT + `agent:read` | Get agent details |
+| `PUT` | `/api/v1/admin/agents/:id` | JWT + `agent:update:own` or `agent:update:all` | Update agent |
+| `DELETE` | `/api/v1/admin/agents/:id` | JWT + delete permission | Delete agent |
+| `POST` | `/api/v1/admin/agents/:id/disable` | JWT + update permission | Kill-switch disable |
+| `POST` | `/api/v1/admin/agents/:id/enable` | JWT + update permission | Re-enable |
+| `POST` | `/api/v1/admin/agents/:id/regenerate-token` | JWT + update permission | Rotate runtime token |
+
+### Runtime/User Routes (`/api/v1/agents`)
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/api/v1/agents/:agentId/invoke` | Flexible auth | Invoke upstream agent runtime |
+| `GET` | `/api/v1/agents/:agentId/credentials-check` | Flexible auth | Pre-check required credentials |
+| `GET` | `/api/v1/agents/:agentId` | Flexible auth | Get public agent info |
+
+## Create Agent
 
 ```bash
 POST /api/v1/admin/agents
@@ -20,73 +41,28 @@ Content-Type: application/json
 }
 ```
 
-**Response** `201 Created`
-
 ```json
 {
-  "id": "agt_...",
-  "name": "Finance Bot",
-  "upstreamUrl": "https://finance-agent.internal/mcp",
-  "isActive": true,
-  "requiredCredentials": [{ "serviceType": "gateway_api" }],
-  "description": "Handles financial queries",
-  "tenantId": "tnt_...",
-  "createdAt": "2025-01-01T00:00:00.000Z"
+  "success": true,
+  "agent": {
+    "id": "agt_...",
+    "name": "Finance Bot",
+    "upstreamUrl": "https://finance-agent.internal/mcp",
+    "hasUpstreamSecret": false,
+    "isActive": true,
+    "requireConfirmation": false,
+    "requiredCredentials": [{ "serviceType": "gateway_api" }],
+    "runtimeTokenPrefix": "art_xxxx",
+    "createdAt": "2026-03-07T12:00:00.000Z"
+  },
+  "runtime_token": "art_..."
 }
 ```
 
-## List Agents
-
-```bash
-GET /api/v1/admin/agents
-Authorization: Bearer <jwt>
-```
-
-## Get Agent
-
-```bash
-GET /api/v1/admin/agents/:id
-Authorization: Bearer <jwt>
-```
-
-## Update Agent
-
-```bash
-PUT /api/v1/admin/agents/:id
-Authorization: Bearer <jwt>
-Content-Type: application/json
-
-{
-  "name": "Updated Finance Bot",
-  "upstreamUrl": "https://new-finance-agent.internal/mcp"
-}
-```
-
-## Delete Agent
-
-```bash
-DELETE /api/v1/admin/agents/:id
-Authorization: Bearer <jwt>
-```
-
-## Disable Agent (Kill Switch)
-
-```bash
-POST /api/v1/admin/agents/:id/disable
-Authorization: Bearer <jwt>
-```
-
-## Enable Agent
-
-```bash
-POST /api/v1/admin/agents/:id/enable
-Authorization: Bearer <jwt>
-```
+`runtime_token` plaintext is only returned on create/rotate.
 
 ## Invoke Agent
 
-Invoke an agent from the frontend. This endpoint is protocol-agnostic -- it forwards the request to the agent's `upstreamUrl` and supports both JSON and SSE streaming responses. The upstream can be any HTTP-based agent runtime (MCP server, CopilotKit agent, Strands/AG-UI agent, or custom service). The Gateway performs credential pre-checks and injects user identity and resolved credentials as headers before forwarding.
-
 ```bash
 POST /api/v1/agents/:agentId/invoke
 Authorization: Bearer <user-jwt>
@@ -97,25 +73,26 @@ Content-Type: application/json
 }
 ```
 
-If required credentials are missing, the response includes auth URLs:
+If credentials are missing:
 
 ```json
 {
-  "status": "CREDENTIALS_REQUIRED",
-  "missingCredentials": [
-    {
-      "serviceType": "gateway_api",
-      "connectUrl": "/auth/connect?service=gateway_api"
-    }
-  ]
+  "code": "CREDENTIALS_REQUIRED",
+  "missing": ["gateway_api"],
+  "authUrls": {
+    "gateway_api": "/auth/connect?service=gateway_api"
+  },
+  "message": "Authentication required for: gateway_api"
 }
 ```
 
-## Pre-check Credentials
+On success, response is JSON-wrapped (`{ success, request_id, data }`) or forwarded SSE stream.
 
-Check credential availability without invoking the agent.
+## Credentials Pre-check
 
 ```bash
 GET /api/v1/agents/:agentId/credentials-check
 Authorization: Bearer <user-jwt>
 ```
+
+Returns `{ ok: true }` when all required credentials are present; otherwise `401` with `CREDENTIALS_REQUIRED` payload.
@@ -1,61 +1,60 @@
 ---
 title: API Keys
-description: Create, list, and revoke Gateway API keys (gk_) for server-to-server authentication.
+description: Admin APIs for creating, listing, and revoking Gateway API keys (`gk_...`).
 ---
 
-All API key management endpoints require JWT authentication (admin).
+## Endpoint Map
 
-## Create API Key
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/api/v1/admin/api-keys` | JWT + role `admin`/`tenant_admin` | Create API key |
+| `GET` | `/api/v1/admin/api-keys` | JWT + role `admin`/`tenant_admin` | List key metadata |
+| `DELETE` | `/api/v1/admin/api-keys/:id` | JWT + role `admin`/`tenant_admin` | Revoke key |
+
+## Scopes
+
+| Scope | Description |
+|---|---|
+| `credentials:resolve` | Resolve/check credentials |
+| `credentials:read` | Read credential metadata |
+| `credentials:write` | Store/update credentials |
+
+## Create Key
 
 ```bash
 POST /api/v1/admin/api-keys
 Authorization: Bearer <jwt>
 Content-Type: application/json
 
 {
-  "name": "Agent Server",
-  "scopes": ["credentials:resolve"]
+  "name": "Agent Runtime",
+  "scopes": ["credentials:resolve"],
+  "expiresAt": "2026-06-01T00:00:00.000Z"
 }
 ```
 
-**Response** `201 Created`
-
 ```json
 {
-  "id": "key_...",
-  "key": "gk_xxx...",
-  "name": "Agent Server",
-  "scopes": ["credentials:resolve"],
-  "keyPrefix": "gk_xxxx",
-  "isActive": true,
-  "createdAt": "2025-01-01T00:00:00.000Z"
+  "success": true,
+  "message": "API key created. Store this key securely — it will not be shown again!",
+  "key": "gk_...",
+  "keyRecord": {
+    "id": "...",
+    "keyPrefix": "gk_xxxx",
+    "name": "Agent Runtime",
+    "scopes": ["credentials:resolve"],
+    "isActive": true
+  }
 }
 ```
 
-The full `key` value is only returned at creation time. Store it securely.
-
-## Available Scopes
+The full `key` is returned only once.
 
-| Scope | Description |
-|-------|-------------|
-| `credentials:resolve` | Resolve credentials for a user |
-| `credentials:read` | Read credential metadata |
-| `credentials:write` | Store or update credentials |
-
-## List API Keys
+## List Keys
 
 ```bash
 GET /api/v1/admin/api-keys
 Authorization: Bearer <jwt>
 ```
 
-Returns key metadata including prefix, name, scopes, and status. The full key is never returned.
-
-## Revoke API Key
-
-```bash
-DELETE /api/v1/admin/api-keys/:id
-Authorization: Bearer <jwt>
-```
-
-Revoking an API key immediately invalidates it. Any agent runtimes using it will receive authentication errors.
+Returns metadata only (never raw key).
@@ -1,60 +1,59 @@
 ---
-title: Audit Logs
-description: Query and retrieve audit logs for tool calls and operations.
+title: Audit
+description: Query audit logs and aggregate audit statistics.
 ---
 
-The audit service tracks every tool call with full context and timing. All audit endpoints require JWT authentication.
+## Endpoint Map
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `GET` | `/api/v1/audit/logs` | JWT | Query audit logs |
+| `GET` | `/api/v1/audit/logs/:id` | JWT | Get one audit log |
+| `GET` | `/api/v1/audit/stats` | JWT + `admin` role | Get aggregate stats |
 
 ## Query Logs
 
 ```bash
-GET /api/v1/audit/logs?userId=xxx&toolName=xxx&status=completed&limit=50
+GET /api/v1/audit/logs?tool_name=slack_send_message&status=failed&limit=50&offset=0
 Authorization: Bearer <jwt>
 ```
 
 ### Query Parameters
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `userId` | string | Filter by user ID |
-| `toolName` | string | Filter by tool name |
-| `status` | string | Filter by status (`pending`, `completed`, `failed`, `confirmed`, `rejected`) |
-| `limit` | number | Max results (default: 50) |
+| Parameter | Description |
+|---|---|
+| `user_id` | Filter by user ID (admins only; non-admin forced to self) |
+| `tenant_id` | Filter by tenant |
+| `tool_name` | Filter by tool |
+| `status` | `pending` `confirmed` `rejected` `completed` `failed` |
+| `start_date` / `end_date` | ISO date range |
+| `limit` / `offset` | Pagination |
 
-**Response** `200 OK`
+Response envelope:
 
 ```json
-[
-  {
-    "id": "log_...",
-    "userId": "usr_...",
-    "toolName": "get_balance",
-    "arguments": { "account_id": "user123" },
-    "result": { ... },
-    "status": "completed",
-    "confirmationId": "cfm_...",
-    "duration": 245,
-    "createdAt": "2025-01-01T00:00:00.000Z"
+{
+  "data": [
+    {
+      "id": "...",
+      "userId": "usr_...",
+      "toolName": "slack_send_message",
+      "status": "failed"
+    }
+  ],
+  "pagination": {
+    "limit": 50,
+    "offset": 0,
+    "total": 1
   }
-]
+}
 ```
 
-Logs for tool calls that required human confirmation include a `confirmationId` linking to the confirmation record.
-
-## Get Single Log
-
-```bash
-GET /api/v1/audit/logs/:id
-Authorization: Bearer <jwt>
-```
-
-## Statistics
-
-Retrieve aggregate audit statistics.
+## Stats
 
 ```bash
 GET /api/v1/audit/stats
-Authorization: Bearer <jwt>
+Authorization: Bearer <admin-jwt>
 ```
 
-Returns counts grouped by status, tool name, and time period.
+Returns `{ data: { total, byStatus, avgDuration } }`.