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). |
Storage
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/_simfra/storage/summary |
Admin | Persistence summary - database size, resource counts by service. |
Response:
{
"enabled": true,
"dataDir": "/data/simfra",
"dbPath": "/data/simfra/simfra.db",
"dbSize": 1048576,
"total": 42,
"services": [{"service": "sqs", "count": 5}, ...]
}
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). |