Admin API Reference

All admin endpoints are served under the /_simfra/ path prefix on the same port as the AWS API (default 4599).

Authentication

When SIMFRA_ADMIN_TOKEN is set, most endpoints require a Authorization: Bearer <token> header. Exceptions are noted below.

---

Health

Method	Path	Auth	Description
GET	/_simfra/health	None	Health check. Returns 200 when ready, 503 while bootstrapping.

Response (200):

{ "status": "healthy", "services": 100, "dockerEnabled": true, "persistenceEnabled": false, "defaultAccountId": "000000000000", "defaultRegion": "us-east-1" }

Response (503):

{ "status": "bootstrapping" }

---

Debug

These endpoints do not require the admin token.

Method	Path	Auth	Description
GET	/_simfra/debug/requests	None	List the last 100 handled requests with status, duration, service, and operation.
GET	/_simfra/debug/requests/{id}	None	Get full detail for a single request including headers and body (up to 64KB).
GET	/_simfra/debug/pprof/	None	Go pprof profiling endpoints (goroutines, heap, CPU).

GET /_simfra/debug/requests - Response:

{
  "inflight": [
    { "id": 42, "started": "...", "method": "POST", "path": "/", "elapsed_ms": 150, "inflight": true }
  ],
  "requests": [
    { "id": 41, "started": "...", "method": "POST", "path": "/", "service": "sqs", "operation": "SendMessage", "status": 200, "duration_ms": 3, "account_id": "000000000000", "region": "us-east-1" }
  ]
}

---

Accounts

Method	Path	Auth	Description
POST	/_simfra/accounts	Admin	Create a new account. Optionally bootstrap it.
GET	/_simfra/accounts	Admin	List all accounts.
GET	/_simfra/accounts/{id}	Admin	Get account details including root credentials.
DELETE	/_simfra/accounts/{id}	Admin	Delete an account and all its service data.
POST	/_simfra/accounts/{id}/reset	Admin	Reset account - deletes all service data but keeps the account.

POST /_simfra/accounts - Request:

{
  "accountId": "123456789012",
  "bootstrap": "standard",
  "region": "us-east-1",
  "availability_zones": ["us-east-1a", "us-east-1b"],
  "vpc_cidr": "172.31.0.0/16"
}

All fields are optional. When accountId is omitted, one is generated. When bootstrap is set, the account is bootstrapped with default VPC infrastructure.

POST /_simfra/accounts - Response (201):

{
  "accountId": "123456789012",
  "rootAccessKeyId": "AKIA...",
  "rootSecretAccessKey": "...",
  "createdAt": "2026-01-15T10:30:00Z",
  "bootstrap": { "success": true }
}

GET /_simfra/accounts - Response:

[
  { "accountId": "000000000000", "alias": "", "createdAt": "2026-01-15T10:30:00Z" }
]

---

Services

Method	Path	Auth	Description
GET	/_simfra/services	Admin	List all registered services with operations.
GET	/_simfra/services?names	Admin	Compact mode - service names only with totals.

Response (compact):

{ "totalServices": 99, "totalOperations": 5529, "services": ["acm", "apigateway", ...] }

Response (full):

{
  "totalServices": 99,
  "totalOperations": 5529,
  "services": [
    { "name": "sqs", "description": "...", "protocols": ["query"], "operationCount": 21, "operations": ["CreateQueue", ...] }
  ]
}

---

Resource ID Overrides

Resource IDs can be overridden at creation time using simfra: tags (for resources that accept tags) or the Simfra Terraform provider (for Route53 zones and Organizations). See Resource ID Overrides for full documentation.

---

Events (SSE)

Method	Path	Auth	Description
GET	/_simfra/events	Query param token	Server-Sent Events stream for real-time UI updates.

Auth is via the token query parameter (since EventSource cannot set headers). Optional accountId query parameter filters events to a single account.

Events are JSON objects with service, type, and action fields. A keepalive comment is sent every 30 seconds.

---

CA (Certificate Authority)

Method	Path	Auth	Description
GET	/_simfra/ca/info	Admin	CA information - root and intermediate cert details.
GET	/_simfra/ca/root.crt	Admin	Download root CA certificate as PEM file.

GET /_simfra/ca/info - Response:

{
  "persistent": true,
  "directory": "/home/user/.simfra/ca",
  "root": { "subject": "...", "serialNumber": "...", "notAfter": "..." },
  "intermediate": { "subject": "...", "serialNumber": "...", "notAfter": "..." }
}

---

Docker

All Docker endpoints require SIMFRA_DOCKER=true. Returns 503 when Docker is disabled.

Method	Path	Auth	Description
GET	/_simfra/docker/summary	Admin	Overview of containers, images, networks, and volumes.
GET	/_simfra/docker/containers	Admin	List all Simfra-managed containers.
GET	/_simfra/docker/containers/{id}	Admin	Inspect a container.
POST	/_simfra/docker/containers/{id}/start	Admin	Start a stopped container.
POST	/_simfra/docker/containers/{id}/stop	Admin	Stop a running container.
POST	/_simfra/docker/containers/{id}/restart	Admin	Restart a container.
GET	/_simfra/docker/containers/{id}/logs	Admin	Get container logs. Query params: tail (number of lines), since (timestamp).
DELETE	/_simfra/docker/containers/{id}	Admin	Remove a container.
GET	/_simfra/docker/images	Admin	List Docker images.
POST	/_simfra/docker/images/pull	Admin	Pull a Docker image. Body: {"image": "name:tag"}.
DELETE	/_simfra/docker/images/{id}	Admin	Remove a Docker image.
GET	/_simfra/docker/networks	Admin	List Simfra-managed Docker networks.
GET	/_simfra/docker/networks/{id}	Admin	Inspect a Docker network.
DELETE	/_simfra/docker/networks/{id}	Admin	Remove a Docker network.
GET	/_simfra/docker/volumes	Admin	List Docker volumes.
DELETE	/_simfra/docker/volumes/{name}	Admin	Remove a Docker volume.
POST	/_simfra/docker/cleanup	Admin	Remove all Simfra-managed containers, networks, and volumes.

---

Port Forwards

Requires Docker to be enabled.

Method	Path	Auth	Description
POST	/_simfra/port-forwards	Admin	Create a port forward to a private container.
GET	/_simfra/port-forwards	Admin	List active port forwards.
GET	/_simfra/port-forwards/targets	Admin	List available port forward targets (containers).
GET	/_simfra/port-forwards/{id}	Admin	Get a port forward session.
DELETE	/_simfra/port-forwards/{id}	Admin	Stop and remove a port forward.

POST /_simfra/port-forwards - Request:

{
  "targetArn": "arn:aws:rds:us-east-1:000000000000:db:mydb",
  "localPort": 5432
}

Response:

{
  "id": "pf-abc123",
  "targetArn": "arn:aws:rds:...",
  "targetIp": "172.18.0.5",
  "targetPort": 5432,
  "localPort": 5432,
  "localAddress": "localhost:5432",
  "vpcNetwork": "simfra-vpc-...",
  "service": "rds",
  "status": "active"
}

---

Inbox

The inbox captures notifications from SES, SNS, Cognito, and Organizations.

Method	Path	Auth	Description
GET	/_simfra/inbox	Admin	List inbox messages. Query params: limit, offset, type, source, search.
DELETE	/_simfra/inbox	Admin	Delete all inbox messages.
GET	/_simfra/inbox/unread-count	Admin	Get unread message count.
POST	/_simfra/inbox/read-all	Admin	Mark all messages as read.
GET	/_simfra/inbox/{id}	Admin	Get a single message.
DELETE	/_simfra/inbox/{id}	Admin	Delete a message.
POST	/_simfra/inbox/{id}/read	Admin	Mark a message as read.
POST	/_simfra/inbox/{id}/action	Admin	Execute the message's action (e.g. confirm SNS subscription).

---

SES

Method	Path	Auth	Description
GET	/_simfra/ses/verify-identity	None	Verify an SES email identity, the simulator's equivalent of clicking the link in the verification email. Returns an HTML confirmation page. Query params: Identity, Token, AccountId, Region. No admin token required so the link works directly from the captured email.

---

Storage

Method	Path	Auth	Description
GET	/_simfra/storage/summary	Admin	Storage summary - persistence state, database size, and live resource counts by service.

Resource counts (total, services) are tallied from live in-memory state, so they are populated whether or not persistence is enabled. When persistence is off, enabled is false and the database fields are omitted, but the counts still reflect the running resources.

Response:

{
  "enabled": true,
  "dataDir": "/data/simfra",
  "dbPath": "/data/simfra/simfra.db",
  "dbSize": 1048576,
  "total": 42,
  "services": [{"service": "sqs", "count": 5}, ...]
}

---

Backup

A full, portable snapshot of every resource across all accounts and regions, plus S3 object bodies, Lambda code, ECR layers, the account registry, and - in Docker mode - Docker engine volume data (RDS/Redshift/ElastiCache/Kafka/MQ/OpenSearch/DSQL/Redshift-Serverless engine databases, EFS files, CodeCommit git repos). Export reads live in-memory state, so it works whether or not persistence is enabled.

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

Export query parameters:

Parameter	Default	Description
volumes	true	Include Docker engine volume data. Set volumes=false to export resource metadata only. Also controlled by SIMFRA_EXPORT_VOLUMES.
quiesce	false	With quiesce=true, each engine's container is stopped for the duration of its volume tar and restarted after, producing an exact (not merely crash-consistent) copy at the cost of brief downtime.

The request body for import is the raw .tar.gz produced by export (Content-Type: application/gzip).

A dump can also be loaded at launch (before serving) by setting the SIMFRA_IMPORT environment variable to a dump path — see Backup & Restore.

POST /_simfra/import - Response:

{
  "resources": 128,
  "resourcesByService": {"sqs": 5, "s3": 3},
  "blobs": 12,
  "accounts": 3,
  "volumes": 4,
  "skippedServices": [],
  "skippedVolumes": [],
  "corrupt": 0
}

volumes counts the engine volumes restored. On a Docker-off instance, volume entries in a format-v2 dump are skipped and listed in skippedVolumes rather than failing the import.

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

---

Request Logs

Method	Path	Auth	Description
POST	/_simfra/request-logs/clear	Admin	Clear all accumulated request log entries.

Request logs are written to SIMFRA_REQUEST_LOG_DIR when that variable is set. This endpoint clears the in-memory log buffer; it does not delete files on disk.

---

Lambda Code Download (Internal)

Used by the Lambda GetFunction response to provide a presigned download URL for function code. Not intended for direct use.

Method	Path	Auth	Description
GET	/_simfra/lambda/code	HMAC signature	Download Lambda function deployment package.

Auth is via HMAC-SHA256 query parameters (account, function, hash, expires, sig) generated by the Lambda service. URLs expire after 10 minutes.

---

Service-Specific Endpoints

Method	Path	Auth	Description
GET	/_simfra/dns/{accountId}	Admin	Get the DNS server port for an account.
GET	/_simfra/smtp/{accountId}	Admin	Get the SMTP relay port for an account.
GET	/_simfra/cognito-auth/{accountId}	Admin	Get the Cognito hosted UI port for an account.

Response:

{ "port": 10053 }

---

ACM (Certificate Manager)

Method	Path	Auth	Description
GET	/_simfra/acm/{accountId}/{region}/pending-validations	Admin	List certificates pending DNS/email validation.
POST	/_simfra/acm/{accountId}/{region}/validate/{certificateARN}	Admin	Validate all domains on a certificate.
POST	/_simfra/acm/{accountId}/{region}/validate/{certificateARN}/{domain}	Admin	Validate a specific domain on a certificate.

---

SSO

Method	Path	Auth	Description
POST	/_simfra/sso/sessions	Admin	Create an SSO portal session for an account.
GET	/_simfra/sso/sessions	Admin	List active SSO sessions.
DELETE	/_simfra/sso/sessions/{token}	Admin	Delete an SSO session.

---

SSO OIDC

Method	Path	Auth	Description
POST	/_simfra/sso-oidc/authorize	Admin	Authorize a pending device code flow.
GET	/_simfra/sso-oidc/device-authorizations	Admin	List pending device authorization requests.
GET	/_simfra/sso-oidc/clients	Admin	List registered OIDC clients.

---

Cognito Hosted UI (Internal)

These endpoints are used by the Cognito hosted UI container and are not intended for direct use.

Method	Path	Auth	Description
POST	/_simfra/cognito-idp/authenticate	Admin	Authenticate a user directly.
POST	/_simfra/cognito-idp/issue-tokens	Admin	Issue OAuth2 tokens for a user.
POST	/_simfra/cognito-idp/refresh-tokens	Admin	Refresh OAuth2 tokens.
POST	/_simfra/cognito-idp/client-credentials-tokens	Admin	Issue client credentials grant tokens.
POST	/_simfra/cognito-idp/revoke-token	Admin	Revoke a token.
POST	/_simfra/cognito-idp/userinfo	Admin	Get user info from an access token.
POST	/_simfra/cognito-idp/signup	Admin	Register a new user.
GET	/_simfra/cognito-idp/{region}/{poolId}/.well-known/jwks.json	Admin	Get JWKS for a Cognito user pool.

---

OIDC Provider JWKS

Method	Path	Auth	Description
GET	/_simfra/oidc/{accountId}/{issuerPath}/.well-known/jwks.json	Admin	Get JWKS for an IAM OIDC provider.

---

Container Credentials (Internal)

Used by ECS tasks and CodeBuild containers to obtain temporary credentials via AWS_CONTAINER_CREDENTIALS_FULL_URI. Not intended for direct use.

Method	Path	Auth	Description
GET	/_simfra/container-credentials/{id}	None	Get temporary credentials for a container workload.

Response (200):

{
  "AccessKeyId": "ASIA...",
  "SecretAccessKey": "...",
  "Token": "...",
  "Expiration": "2026-01-15T11:30:00Z"
}

Returns 404 if the container ID is not registered.

---

WebSocket Endpoints

These endpoints upgrade to WebSocket connections and use their own auth mechanisms.

Method	Path	Auth	Description
WS	/_simfra/cloudshell/connect	Query param token	CloudShell terminal session. Query params: accountId, region.
WS	/_simfra/browser/connect	Query param token	Embedded browser session.
WS	/_simfra/ssm/web-terminal	None	SSM Session Manager browser terminal. Query params: accountId, region, instanceId.
WS	/_simfra/ssm/data-channel/{sessionId}	Query param token	SSM Session Manager data channel (used by aws ssm start-session).