Multi-Account Support

Simfra supports multiple AWS accounts. Each account has its own resources, credentials, and isolation - just like real AWS.

Default Account

On startup, Simfra creates a default account with ID 000000000000. The default credentials are:

Setting	Default	Environment Variable
Account ID	000000000000	SIMFRA_DEFAULT_ACCOUNT_ID
Access Key ID	AKIAIOSFODNN7EXAMPLE	SIMFRA_ROOT_ACCESS_KEY_ID
Secret Access Key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY	SIMFRA_ROOT_SECRET_ACCESS_KEY

Creating Accounts

Create a new account via the admin API:

curl -X POST http://localhost:4599/_simfra/accounts \
  -H "Content-Type: application/json" \
  -d '{"accountId": "111111111111"}'

The response includes root credentials for the new account:

{
  "accountId": "111111111111",
  "rootAccessKeyId": "AKIA...",
  "rootSecretAccessKey": "...",
  "createdAt": "2025-01-15T10:30:00Z"
}

Bootstrap on Creation

To create an account with default VPCs, KMS keys, and IAM service-linked roles, include "bootstrap" in the request:

curl -X POST http://localhost:4599/_simfra/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "111111111111",
    "bootstrap": "standard",
    "region": "us-east-1"
  }'

Optional fields:

Field	Default	Description
bootstrap	(empty)	"standard" to create default VPC, KMS keys, and SLRs
region	Server default	Region for bootstrap resources
availability_zones	Region defaults	Override AZ list
vpc_cidr	172.31.0.0/16	CIDR for the default VPC

Managing Accounts

List Accounts

curl http://localhost:4599/_simfra/accounts

Returns an array of all accounts with IDs, aliases, and creation timestamps.

Get Account Details

curl http://localhost:4599/_simfra/accounts/111111111111

Returns account details including root credentials. Use this to retrieve the access key and secret key for a specific account.

Delete Account

curl -X DELETE http://localhost:4599/_simfra/accounts/111111111111

Deletes the account and all its resources across all services and regions.

Reset Account

curl -X POST http://localhost:4599/_simfra/accounts/111111111111/reset

Clears all resources in the account without deleting it. The account retains its ID and credentials.

Using Account Credentials

Each account has its own root access key and secret key. Configure the AWS CLI or SDK to use a specific account's credentials:

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_ENDPOINT_URL=http://localhost:4599

aws s3 ls  # Lists buckets in the account associated with these credentials

Or use named profiles:

# ~/.aws/credentials
[simfra-dev]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[simfra-staging]
aws_access_key_id = AKIA...     # from account creation response
aws_secret_access_key = ...

Organizations

For multi-account management with organizational units and service control policies, use the AWS Organizations service:

# Create an organization
aws organizations create-organization --endpoint-url http://localhost:4599

# Create an OU
aws organizations create-organizational-unit \
  --parent-id r-root \
  --name Production \
  --endpoint-url http://localhost:4599

# Attach a service control policy
aws organizations attach-policy \
  --policy-id p-abc123 \
  --target-id ou-root-prod \
  --endpoint-url http://localhost:4599

SCPs attached via Organizations are enforced by the IAM evaluation chain on every API call in member accounts.

Securing the Admin API

By default, the admin API is unauthenticated. Set SIMFRA_ADMIN_TOKEN to require a Bearer token:

export SIMFRA_ADMIN_TOKEN=my-secret-token

Then include it in requests:

curl -H "Authorization: Bearer my-secret-token" \
  http://localhost:4599/_simfra/accounts

Health checks (GET /_simfra/health) do not require authentication.