Admin API

All admin endpoints live under /_simfra/. These are Simfra-specific - not part of any AWS API.

Authentication

When SIMFRA_ADMIN_TOKEN is set, all admin endpoints (except health and a few WebSocket/SSE endpoints that use query param auth) require a Bearer token:

Authorization: Bearer <token>

WebSocket and SSE endpoints accept the token as a ?token= query parameter since browsers cannot set headers on WebSocket or EventSource connections.

Health checks (GET /_simfra/health) never require authentication.

Account Management

Method	Path	Description
POST	/_simfra/accounts	Create account (optional bootstrap field)
GET	/_simfra/accounts	List all accounts
GET	/_simfra/accounts/{id}	Get account details with credentials
DELETE	/_simfra/accounts/{id}	Delete account and all resources
POST	/_simfra/accounts/{id}/reset	Clear all resources in account

See Multi-Account Support for details.

Service Discovery

Method	Path	Description
GET	/_simfra/services	List all services with descriptions, protocols, and operations
GET	/_simfra/services?names	Compact list: service names and total counts only

The full response includes each service's name, description, supported protocols, operation count, and operation names.

Health

Method	Path	Description
GET	/_simfra/health	Server health, service count, Docker and persistence status

Returns 503 during bootstrap, 200 when ready:

{
  "status": "healthy",
  "services": 88,
  "dockerEnabled": true,
  "persistenceEnabled": false
}

SSE Event Stream

Method	Path	Description
GET	/_simfra/events	Server-Sent Events stream for real-time change notifications

Query parameters:

• accountId - filter events by account
• token - admin token (for auth)

The web console uses this to invalidate stale data without polling. Events include the service, resource type, and action (e.g., {"service": "s3", "type": "buckets", "action": "mutated"}).

Certificate Authority

Method	Path	Description
GET	/_simfra/ca/info	Root and intermediate CA certificate details
GET	/_simfra/ca/root.crt	Download root CA certificate (PEM)

The root CA is used by Docker containers for TLS trust. Download it to trust Simfra-issued certificates on your host.

Docker Management

Requires SIMFRA_DOCKER=true.

Method	Path	Description
GET	/_simfra/docker/summary	Overview of containers, images, networks, volumes
GET	/_simfra/docker/containers	List all Simfra-managed containers
GET	/_simfra/docker/containers/{id}	Inspect a container
POST	/_simfra/docker/containers/{id}/start	Start a container
POST	/_simfra/docker/containers/{id}/stop	Stop a container
POST	/_simfra/docker/containers/{id}/restart	Restart a container
GET	/_simfra/docker/containers/{id}/logs	Stream container logs
DELETE	/_simfra/docker/containers/{id}	Remove a container
GET	/_simfra/docker/images	List Docker images
POST	/_simfra/docker/images/pull	Pull an image
DELETE	/_simfra/docker/images/{id}	Remove an image
GET	/_simfra/docker/networks	List Docker networks
GET	/_simfra/docker/networks/{id}	Inspect a network
DELETE	/_simfra/docker/networks/{id}	Remove a network
GET	/_simfra/docker/volumes	List Docker volumes
DELETE	/_simfra/docker/volumes/{name}	Remove a volume
POST	/_simfra/docker/cleanup	Remove all Simfra containers, networks, and volumes

Port Forwarding

Requires SIMFRA_DOCKER=true.

Method	Path	Description
POST	/_simfra/port-forwards	Create a port forward to a private container
GET	/_simfra/port-forwards	List active port forwards
GET	/_simfra/port-forwards/targets	List available targets (private containers)
GET	/_simfra/port-forwards/{id}	Get port forward details
DELETE	/_simfra/port-forwards/{id}	Delete a port forward

Message Inbox

Method	Path	Description
GET	/_simfra/inbox	List messages (supports ?type=, ?source=, ?search=, ?limit=, ?offset=)
GET	/_simfra/inbox/unread-count	Get unread message count
POST	/_simfra/inbox/read-all	Mark all messages as read
DELETE	/_simfra/inbox	Delete all messages
GET	/_simfra/inbox/{id}	Get a single message
POST	/_simfra/inbox/{id}/read	Mark message as read
DELETE	/_simfra/inbox/{id}	Delete a message
POST	/_simfra/inbox/{id}/action	Execute message action (e.g., confirm SNS subscription)

See Message Inbox for details.

Storage

Method	Path	Description
GET	/_simfra/storage/summary	Persistence stats: DB size, resource counts by service

Backup (Export / Import)

A full, portable snapshot of everything Simfra is managing — all resources across every account and region, plus S3 object bodies, Lambda code, ECR layers, and the account registry. Works whether or not persistence is enabled (state is read from live memory, not the SQLite file).

Method	Path	Description
GET	/_simfra/export	Stream a full system dump as a gzipped tar (simfra-dump.tar.gz)
POST	/_simfra/import	Restore a dump; replaces in-memory state with the dump's contents

# Snapshot a running Simfra to a file
curl -s http://localhost:4599/_simfra/export -o simfra-dump.tar.gz

# Restore it (into the same or a different Simfra instance)
curl -s -X POST --data-binary @simfra-dump.tar.gz http://localhost:4599/_simfra/import

The import response is a JSON summary of what was applied:

{ "resources": 128, "blobs": 12, "accounts": 3, "skippedServices": [], "corrupt": 0 }

To load a dump at launch instead of POSTing to a running server, set SIMFRA_IMPORT=<dump path> — the dump is imported before the server starts serving.

See Backup & Restore for the dump format, semantics, launch loading, and limitations.

CloudShell

Method	Path	Description
WS	/_simfra/cloudshell/connect	WebSocket for terminal session

Query parameters: accountId, region, token.

See CloudShell for details.

Embedded Browser

Method	Path	Description
WS	/_simfra/browser/connect	WebSocket for browser VNC session

Query parameters: accountId, token.

See Embedded Browser for details.

SSM Web Terminal

Method	Path	Description
WS	/_simfra/ssm/web-terminal	WebSocket for EC2 instance shell

Query parameters: accountId, region, instanceId.

See EC2 Instance Connect for details.

Service-Specific Endpoints

DNS

Method	Path	Description
GET	/_simfra/dns/{accountId}	Get DNS container host port for an account

SES SMTP

Method	Path	Description
GET	/_simfra/smtp/{accountId}	Get SMTP relay host port for an account

Cognito Hosted UI

Method	Path	Description
GET	/_simfra/cognito-auth/{accountId}	Get Cognito hosted UI host port
POST	/_simfra/cognito-idp/authenticate	Authenticate user directly
POST	/_simfra/cognito-idp/issue-tokens	Issue tokens for a user
POST	/_simfra/cognito-idp/refresh-tokens	Refresh tokens
POST	/_simfra/cognito-idp/signup	Sign up a user
GET	/_simfra/cognito-idp/{region}/{poolId}/.well-known/jwks.json	Cognito JWKS endpoint

ACM Certificate Validation

Method	Path	Description
GET	/_simfra/acm/{accountId}/{region}/pending-validations	List pending certificate validations
POST	/_simfra/acm/{accountId}/{region}/validate/{arn}	Validate all domains on a certificate
POST	/_simfra/acm/{accountId}/{region}/validate/{arn}/{domain}	Validate a specific domain

SSO Sessions

Method	Path	Description
POST	/_simfra/sso/sessions	Create SSO session
GET	/_simfra/sso/sessions	List SSO sessions
DELETE	/_simfra/sso/sessions/{token}	Delete SSO session

SSO OIDC

Method	Path	Description
POST	/_simfra/sso-oidc/authorize	Authorize a device
GET	/_simfra/sso-oidc/device-authorizations	List device authorizations
GET	/_simfra/sso-oidc/clients	List registered clients

OIDC Provider JWKS

Method	Path	Description
GET	/_simfra/oidc/{accountId}/{issuer}/.well-known/jwks.json	OIDC provider JWKS endpoint