Admin API
REST, GraphQL, and WebSocket admin surface on core — auth, scope, health, and MCP relationship.
The Admin API runs on core (default ADMIN_BASE_URL → port 3030). It powers the Conduit Admin Panel, CI provisioning scripts, and the MCP server. Application code must not call it from user-facing paths.
For AI agents
Apps use the Client API on the router (:3000) with user bearer tokens. See Client vs Admin API.
Comparison
| Admin API | Client API | |
|---|---|---|
| Host | Core (:3030) | Router module (:3000) |
| Consumers | Admin panel, MCP, operators, CI | Web/mobile apps, user-scoped server routes |
| Auth | masterkey header, admin JWT (Bearer), or cdt_ API tokens | User tokens from authentication module |
| Database | Schema/endpoint/index admin, extensions | /database/{Schema}, /database/function/{name} |
| Response shape | Paginated lists, admin metadata, detailed errors | Streamlined payloads for app consumption |
| MCP | Subset exposed as MCP tools | Not exposed through MCP |
Response formats are not interchangeable between Admin and Client APIs.
Health endpoints
No authentication required:
| Method | Path | Purpose |
|---|---|---|
| GET | /live | Liveness — shallow; { status: "alive", message: "..." } |
| GET | /ready | Readiness — deep; structured report with per-check pass/fail/warn |
/ready returns 503 when not ready (e.g. required module not registered, Redis down). Use Accept: application/json for the full report; legacy plain-text clients get Conduit Core is online! / Conduit Core is not ready (or ?legacy=true).
Configure required modules and probe behavior via READY_* env vars — see Environment variables.
Authentication
| Method | Usage |
|---|---|
masterkey | Header on trusted bootstrap/ops scripts |
| Admin JWT | Authorization: Bearer <token> after POST /login |
cdt_ API tokens | Long-lived tokens for automation and MCP clients |
API tokens (cdt_)
| Method | Path | Notes |
|---|---|---|
| POST | /api-tokens | Body: { name, expiresInDays? } — returns plaintext cdt_… once |
| GET | /api-tokens | Lists metadata (tokenPrefix, lastUsedAt) — never the secret |
| DELETE | /api-tokens/:id | Revoke; admins can only delete their own tokens |
Token format: cdt_ + base64url random bytes. Prefix (cdt_xxxxxxxx) is stored for lookup; full value is bcrypt-hashed server-side.
v0.17 breaking change: Client API authentication service accounts (POST /authentication/service) are removed. Migrate automation and CI from service-account credentials to cdt_ tokens created here. See Migration v0.16 → v0.17.
Never embed admin credentials in application code, browser env vars, or client bundles.
Surfaces
Core exposes Admin API over:
- REST — module routes registered via
RoutingManager(e.g./database/schemas,/config/{module}) - GraphQL — admin schema aggregation
- WebSockets — admin realtime where modules register handlers
Interactive reference: Admin API Swagger (available on a running instance). MCP also exposes conduit://docs/admin-api/swagger as a resource when connected.
MCP relationship
The MCP server at {ADMIN_BASE_URL}/mcp wraps a subset of Admin API operations as tools. Routes with mcp: false (database import/introspection, login, credential management) are excluded. Authentication is handled by the MCP connection — tools run with admin privileges.
- Call
list_modulesto see loaded modules - Enable more tools via
/mcp?modules=authentication,database,storage,authorization - Tool naming: HTTP method + path with
/→_(see MCP tools)
MCP is for development and deploy-time provisioning only. Do not substitute MCP calls for Client API calls in application runtime.
When to use Admin API
| Task | Surface |
|---|---|
| Create or patch schemas, indexes, custom endpoints | Admin API or MCP |
| Patch module config (auth providers, storage buckets, email templates) | Admin API or MCP |
| Manage admin users, API tokens, teams (operator workflows) | Admin API or MCP |
Bulk ReBAC tuples (POST /authorization/relations/many) | Admin API or MCP (post_authorization_relations_many) |
| Export/import platform state (GitOps) | GET /state/export, POST /state/import — GitOps guide |
| Database introspection or schema import | Admin API / panel only — not MCP |
| End-user login, CRUD, permission checks | Client API only |
| Application file upload/download | Client API with user token |
Rules
- Never call Admin API from user-facing request paths.
- Never expose
masterkey, admin JWTs, orcdt_tokens to browsers. - Provision schemas, endpoints, and config at dev/deploy time — not on app startup or per user action.
- For filtered or authorization-sensitive queries in apps, provision custom endpoints and call them on the Client API.