Cloud Account Structure

Production-grade guide to cloud account structure covering architecture patterns, implementation strategies, testing approaches, and operational best practices for enterprise engineering teams.

This reference describes how cloud accounts are organised to support multi-tenancy, access control, and resource isolation. It matters when setting up new projects, troubleshooting access issues, or auditing account permissions.

Understanding Account Boundaries

A cloud account defines the boundary for all resources and access policies within a single administrative unit. Every resource must belong to exactly one account, and accounts cannot directly share resources across boundaries. The account acts as both identity container and billing unit.

Creating New Accounts

To create a new account, use the account creation endpoint with required fields including name, owner email, and optional tags. The system validates that the account name is unique within the parent organisation.

POST /api/v1/accounts
Content-Type: application/json

{
  "name": "project-alpha",
  "owner_email": "[email protected]",
  "description": "Development environment for project alpha",
  "tags": {
    "environment": "development",
    "team": "frontend"
  }
}

The response includes the account ID and creation timestamp.

Account Configuration

Each account has a configuration object that defines access policies, billing settings, and resource limits. The configuration key access_policy controls which identities can manage the account.

{
  "account_id": "acc-12345",
  "access_policy": {
    "allowed_principals": [
      "user:[email protected]",
      "group:devops-team"
    ],
    "require_mfa": true
  }
}

The account configuration is immutable except for tags and description. Changes to access policy require a separate approval process.

Resource Organization Within Accounts

Resources within accounts are grouped into organisational units called "folders". Each folder supports nested structure up to five levels deep. Folders can have their own access policies that inherit from parent folders.

Creating Folders

Folders are created with a POST request to the folders endpoint, including parent folder ID and access control settings.

POST /api/v1/folders
Content-Type: application/json

{
  "name": "backend-services",
  "parent_folder_id": "folder-abcde",
  "access_control": {
    "readers": ["group:backend-team"],
    "writers": ["user:[email protected]"]
  }
}

Folders cannot be moved between accounts. Resources must be migrated manually when moving from one account to another.

Resource Assignment

Resources are assigned to folders during creation by specifying the folder ID in resource creation requests. If no folder is specified, resources default to a root-level folder.

POST /api/v1/resources
Content-Type: application/json

{
  "name": "database-instance",
  "folder_id": "folder-xyz123",
  "type": "rds-instance",
  "configuration": {
    "engine": "postgres",
    "size": "m5.large"
  }
}

Access Control Within Accounts

Access to account resources is controlled through identity-based permissions. Each account maintains a list of principals who can perform actions on resources within that account.

Principal Types

Principals in cloud accounts can be users, groups, or service identities. User principals use email addresses. Group principals use UUIDs prefixed with "group:". Service principals use a format like "service:app-name".

{
  "principals": [
    "user:[email protected]",
    "group:backend-team",
    "service:billing-app"
  ]
}

Permission Models

Permissions are defined using role-based access control (RBAC). Roles define sets of actions that can be performed on resources. Each role can be assigned to any principal within the account.

{
  "roles": {
    "resource-admin": {
      "permissions": ["read", "write", "delete"],
      "scope": "account"
    },
    "viewer": {
      "permissions": ["read"],
      "scope": "folder"
    }
  }
}

Access Policy Enforcement

Access policies are enforced at the account level. When a principal attempts to access a resource, the system checks if they have appropriate permissions through their assigned roles.

Account Limitations and Constraints

Each account has specific limits that affect how many resources can be created and managed. These limits include maximum number of folders, maximum number of principals, and maximum concurrent operations.

Resource Limits

Accounts have soft limits on folder creation and resource count. Exceeding limits causes operations to fail with HTTP 429 status codes.

PUT /api/v1/resources/instance-123
Content-Type: application/json

{
  "name": "new-database",
  "type": "rds-instance"
}

Response for exceeded limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "error": "account_limit_exceeded",
  "message": "Maximum number of resources reached for this account"
}

Billing and Cost Allocation

Accounts are the unit of billing in cloud environments. Each account has a unique billing identifier that appears on all invoices. Resource usage is charged to the account where the resource was created.

Troubleshooting Account Issues

Common issues with account structure include access denied errors, resource creation failures, and permission inheritance problems.

Access Denied Errors

When a principal cannot access a resource, check if they are properly assigned to the account and have appropriate roles. The error response includes the missing permission and required role.

GET /api/v1/resources/database-123
HTTP/1.1 403 Forbidden

{
  "error": "access_denied",
  "required_permission": "read",
  "missing_role": "viewer"
}

Resource Creation Failures

Creating resources fails when the account has exceeded its limits or when the folder ID is invalid. Invalid folder IDs cause HTTP 400 responses with specific error messages.

POST /api/v1/resources
Content-Type: application/json

{
  "name": "test-instance",
  "folder_id": "invalid-folder-id"
}

Response:

HTTP/1.1 400 Bad Request
{
  "error": "invalid_folder",
  "message": "Folder with ID invalid-folder-id does not exist in this account"
}

Migration Between Accounts

Moving resources between accounts requires careful planning and execution. Resources cannot be moved directly; they must be deleted from the source account and recreated in the target account.

Migration Process

To migrate a resource, first export its configuration, then delete it from the source account, and finally create a new resource with identical settings in the target account.

# Export resource configuration
curl -X GET /api/v1/resources/database-123 \
  -H "Authorization: Bearer $TOKEN" > config.json

# Delete from source account
curl -X DELETE /api/v1/resources/database-123 \
  -H "Authorization: Bearer $TOKEN"

# Create in target account
curl -X POST /api/v1/resources \
  -H "Authorization: Bearer $TOKEN" \
  -d @config.json

Data Loss Risks

Migration may result in data loss if the resource has external dependencies. For example, DNS records pointing to the old resource will need manual update after migration.

Account Deletion and Cleanup

Accounts can be deleted when no longer needed, but deletion is irreversible. Before deletion, all resources must be migrated or archived.

Deletion Requirements

Before account deletion, verify that:

  1. All resources have been moved to other accounts
  2. All folder structures are properly migrated
  3. Access policies are backed up for reference
DELETE /api/v1/accounts/acc-12345
Authorization: Bearer $TOKEN

If any resources remain, the deletion fails with HTTP 409 status code.

Cleanup Considerations

After deletion, the account ID becomes available for reuse. However, historical access logs and audit trails remain accessible through a separate API endpoint for a defined retention period.

Account Audit and Monitoring

Account structure changes are tracked through audit logs that include who made the change, when it occurred, and what was modified.

Audit Log Access

Audit logs can be retrieved using a time-range filter. Each log entry includes the principal responsible for the action and the specific changes made.

GET /api/v1/accounts/acc-12345/audit?start_time=2023-01-01T00:00:00Z&end_time=2023-01-02T00:00:00Z
Authorization: Bearer $TOKEN

The response includes a list of events with timestamps and change details.

Monitoring Access Changes

Access policy changes are monitored through webhook notifications. When access policies change, systems can automatically trigger compliance checks or send alerts to administrators.

Account Recovery Procedures

In case of account corruption or accidental deletion, recovery procedures restore accounts from backups.

Recovery Process

Recovery requires contacting cloud support with the account ID and backup timestamp. The system restores all folder structures and resource configurations from the specified backup point.

Data Consistency

After recovery, verify that:

  1. All folders exist with correct hierarchy
  2. Resource configurations match the backup
  3. Access policies are properly applied to all resources
  4. No orphaned resources remain in the account

Recovery operations may take several hours depending on account size and complexity.

This page was rewritten on 16 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.