systemprompt-api 0.58.0

Axum-based HTTP server and API gateway for systemprompt.io AI governance infrastructure. Exposes governed agents, MCP, A2A, and admin endpoints with rate limiting and RBAC.
Documentation

systemprompt-api

Crates.io Docs.rs codecov License: BSL-1.1

Composes Axum routes and middleware for authentication, agents, MCP, inference, marketplace, analytics and administration. Enforcement and authentication requirements are specific to each route.

Layer: Entry — application boundary. Part of the systemprompt-core workspace.

This crate exposes a public library surface (ApiServer, route routers, middleware extractors) consumed by entry/cli.

Overview

The Entry layer turns an AppContext into a running Axum server. Responsibilities:

  • Route mounting — every domain crate's router is composed under one tree by services/server/routes/.
  • Middleware stack — JWT, sessions, CORS, IP ban, rate limiting, throttling, bot detection, analytics emission, context extraction, content negotiation, security headers, and trailing-slash normalization.
  • Gateway — proxies Claude API traffic with quota enforcement, safety filtering, OTel ingest, audit, and pricing capture.
  • Static content — serves the prebuilt web frontend with ETag, SPA fallback, and per-route session handling.
  • Server lifecycle — readiness probes, agent reconciliation, and scheduler bootstrap.

Source layout

Top-level modules. docs.rs carries the file-level detail.

src/
├── lib.rs        # Re-exports: HealthChecker, ContextMiddleware
├── routes/       # Per-domain HTTP routers, one module per surface (see Route surface)
└── services/     # Server lifecycle, middleware pipeline, gateway, proxy, static content (see Service surface)
Module Purpose
routes One router module per surface (agent, gateway, oauth, mcp, proxy, messaging, and the rest), composed into a single tree by services/server/routes/.
services/server ApiServer builder, route/extension/protocol/static mounting under routes/, readiness, lifecycle (agent reconciliation + scheduler), and the run_server entry point.
services/middleware Request pipeline: JWT, session, context extraction, analytics, CORS, IP ban, rate limiting, throttling, bot detection, content negotiation, security headers, trailing-slash normalization.
services/gateway ClaudeGatewayService: quota, audit, safety, pricing, protocol, stream tap, OTel capture.
services/proxy ProxyEngine: client pool, backend transform, resolver, MCP session handling for upstream A2A and MCP targets.
services/static_content SPA serving, homepage, static-file cache and response building, fallback routing.

Route surface

Module Description
admin CLI gateway and key-management endpoints.
agent A2A protocol — artifacts, contexts, tasks, registry, webhook broadcasts, notifications.
analytics Event ingestion, batch processing, and SSE streaming.
content Blog, content queries, and link redirect tracking.
engagement Engagement metrics fan-out from analytics events.
gateway Claude API gateway: bridge auth/data/heartbeat/manifest/profile-usage/whoami, message dispatch, OTLP ingest.
marketplace Marketplace catalog and asset endpoints.
mcp MCP server registry.
messaging Platform-agnostic inbound dispatch shared by chat platforms: identity, per-user A2A token minting, blocking message/send through the proxy, reply extraction.
oauth OAuth2/OIDC authorize, token, clients, WebAuthn, discovery, and .well-known metadata.
proxy Forwards requests to MCP servers and A2A agents through ProxyEngine.
slack Slack inbound surface (/events, /commands, /interactivity): signature verification, ack, spawned dispatch, Block Kit reply.
stream Server-Sent Events for live context updates.
sync File and auth sync for offline-first clients (tar+gzip payloads).
teams Microsoft Teams inbound surface (/messages): Bot Framework JWT validation, ack, spawned dispatch, Adaptive Card reply.
users Self-service /me endpoints scoped to the caller, including session revocation.
wellknown Standard discovery endpoints (agent cards, OAuth protected resource).

Service surface

Module Description
gateway Claude gateway service — quota, audit, safety, pricing, stream tap, OTel capture.
health Process monitoring and HTTP health checks.
middleware Request pipeline: JWT, session, context, analytics, CORS, IP ban, rate limiting, throttling, security headers, content negotiation, trailing-slash normalization.
proxy HTTP client pool and request transformation for upstream MCP and A2A targets.
server Builder, route tree, readiness, lifecycle (agent reconciliation + scheduler), and runner.
static_content SPA serving, homepage, static-file cache and response building, fallback routing.

Usage

[dependencies]
systemprompt-api = "0.58"

use systemprompt_api::services::server::{run_server, setup_api_server};
use systemprompt_runtime::AppContext;

let ctx = AppContext::new().await?;
run_server(ctx, None).await?;

Configuration

The API server is configured through systemprompt-runtime::Config and the active profile:

  • api_external_url — public URL advertised in discovery metadata.
  • rate_limits — per-endpoint rate limit configuration.
  • security.signing_key_path — RSA private key the in-process TokenAuthority uses to sign RS256 access tokens. The matching public set is published at /.well-known/jwks.json; systemprompt admin keys generate mints the keypair.
  • security.trusted_issuers — additional issuer → JWKS URI entries consulted by the RFC 8693 token-exchange grant when validating non-self-issued subject tokens.
  • oauth_at_rest_pepper — HMAC pepper (>= 32 chars, loaded via the secrets bootstrap) under which refresh-token ids and authorisation codes are stored as HMAC-SHA-256 digests.
  • cors — allowed origins.
  • paths.system — root used by static_content to locate prebuilt web assets.

Notes

  • Handlers extract request data and delegate to domain services; no direct repository access.
  • All routes are composed in services/server/routes/; extensions are discovered via services/server/discovery.rs.
  • Middleware order is significant — see services/server/builder.rs.
  • The gateway path mints a UUID v5 ContextId from GatewayConversationId; it does not read upstream x-context-id.
  • Static content requires prebuilt web assets under the configured system path.

Dependencies

Internal crates

  • systemprompt-runtime — application context and configuration
  • systemprompt-oauth — authentication and session management
  • systemprompt-agent — agent registry, A2A protocol, orchestration
  • systemprompt-mcp — MCP server registry and proxy
  • systemprompt-content — content repository and serving
  • systemprompt-analytics — session and event tracking
  • systemprompt-scheduler — background job execution
  • systemprompt-marketplace — marketplace catalog
  • systemprompt-ai — Claude gateway integrations
  • systemprompt-database — connection pooling
  • systemprompt-security — token extraction and validation
  • systemprompt-users — user services and IP banning
  • systemprompt-events — event broadcasting
  • systemprompt-files — file system configuration
  • systemprompt-extension — extension loading and routing
  • systemprompt-config, systemprompt-loader, systemprompt-logging, systemprompt-models, systemprompt-identifiers, systemprompt-traits

External crates

  • axum, tower, tower-http, tower_governor, governor — HTTP framework and middleware
  • tokio, tokio-stream, async-stream, futures-util — async runtime
  • reqwest — upstream HTTP client
  • rmcp — MCP transport
  • jsonwebtoken, webauthn-rs, bcrypt, ed25519-dalek — auth primitives
  • opentelemetry-proto, prost — OTLP ingest
  • flate2, tar — sync payload (de)compression
  • sqlx — database access

License

BSL-1.1 (Business Source License). Source-available for evaluation, testing, and non-production use. Production use requires a commercial license. Each version converts to Apache 2.0 four years after publication. See LICENSE.