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

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