Platform

Developer sub-accounts

Sub-accounts are API-first, non-human Hubfly space tenants owned by a personal account or organization. Use them to give each customer, product, agent, or automation an isolated wallet and cloud environment.

Sub-accounts are tenants, not team members

A sub-account has no password, login, invitations, or independent owner. Authorized members of the parent operate it, and software authenticates with a platform or tenant-bound machine credential.

Tenant model

Every sub-account has a public sub_ identifier and a backing organization used internally as the established ownership boundary for projects, usage, Scheduler billing, and balance enforcement. Backing organizations are hidden from ordinary organization lists and cannot receive members or invitations.

A parent can be one personal account or one organization.
Each tenant has its own canonical paid and promotional wallet balances.
Resources remain ordinary Hubfly space projects and project resources owned by the backing organization.
An optional externalRef connects the tenant to a customer or object in your own system and is unique inside the parent.
Sub-accounts are one level deep. A sub-account cannot create another sub-account.
Changing or transferring the parent is not supported.

Applications

Pattern	How sub-accounts help
SaaS customer infrastructure	Provision a dedicated wallet, project namespace, credentials, and audit context for each customer.
AI agents	Give each agent or automation a revocable identity and bounded tenant instead of a human credential.
Managed hosting	Operate multiple client environments from one parent without mixing balances or resources.
Preview platforms	Create and retire isolated integration, branch, QA, and demo environments programmatically.
Internal developer portals	Expose a curated provisioning interface backed by Hubfly space’s API and parent platform credentials.

Supported features

A tenant can use the core Hubfly space cloud surface through the same resource endpoint paths as a normal account:

Projects: projects, project budgets, and ordinary project permissions.
Compute: containers, builds, deployments, Compose, logs, exec, terminals, and tunnels.
Storage: volumes and scoped file sessions.
Registry: images, credentials, tokens, scanning, and deployment webhooks.
Networking: subdomains, custom domains, ports, load balancers, firewall, route access, redirects, TLS, and caching.
Operations: wallet funding, balance enforcement, machine attribution, API/SDK/CLI access, suspension, and closure.

Features that require a human identity are excluded

GPU instances and the separate GPU wallet, GitHub OAuth identity and repository discovery, educational/team membership, invitations, personal profiles and sessions, payment methods, and unaudited marketplace or managed-tool ownership paths are not available to sub-account machine principals.

Parent access

Humans continue using their existing parent roles. A sub-account never adds its own member records.

Parent role	Sub-account authority
Personal parent owner	Owner-equivalent access.
Organization owner	All operations, wallet transfers, credentials, suspension, and closure.
Organization admin	Create, update, suspend, resume, and operate resources; cannot transfer funds, manage credentials, or close.
Billing	Wallet, usage, and invoice visibility according to the parent role.
Developer, operator, viewer	The corresponding existing resource permissions after tenant enforcement.

Credential scopes and project restrictions only reduce authority. They never grant a permission the parent principal does not have.

Credentials

Tenant-bound keys

An hfsk_ key is permanently bound to one tenant. Resource endpoints infer the tenant from the key, so no tenant header is required.

Tenant-bound request

curl https://api.hubfly.space/api/v1/projects   -H "Authorization: Bearer $HUBFLY_TOKEN"

The “master” preset means broad access to supported resources inside that tenant. It does not allow funding, closure, credential management, parent changes, or access to parent resources.

Parent platform keys

An hfpk_ key belongs to the parent and can manage its sub-accounts. For ordinary resource endpoints, select the effective tenant with X-HubFly-Subaccount.

Platform key targeting a tenant

curl https://api.hubfly.space/api/v1/projects   -H "Authorization: Bearer $HUBFLY_PLATFORM_TOKEN"   -H "X-HubFly-Subaccount: sub_01…"

Platform scopes include subaccounts:read, subaccounts:manage, subaccounts:fund, subaccounts:keys:manage, and subaccounts:operate.

Isolation rules

An hfsk_ key cannot change its tenant. A conflicting header receives 403 SUBACCOUNT_SCOPE.
A platform key must target a tenant owned by its parent. Missing, foreign, or conflicting context is rejected before endpoint execution.
Machine principals are denied by default. An endpoint must explicitly support platform-control or tenant-resource access.
Credential headers are redacted and activity is attributed to the service principal, not its human creator.
Use multiple overlapping keys for rotation, then revoke the old key after traffic moves.

Wallet and billing

Sub-account balances use integer micro-USD. 1000000 equals USD 1.00. A transfer atomically debits only the parent’s paid balance and credits the tenant; promotional credit cannot be transferred.

Use a stable Idempotency-Key for every funding attempt.
Immutable transfer records retain the amount and resulting balances for audit.
Scheduler usage deducts the same canonical balance displayed by Dashboard.
Ordinary zero-balance enforcement applies to tenant-owned projects.
Notifications identify the affected tenant and go to eligible parent owners or billing contacts.
Automatic top-up is not available in the first release.

Lifecycle

Status	Behavior
`active`	Credentials and supported resource operations are enabled subject to balance and permissions.
`suspended`	Credentials and mutations are disabled. The current release does not automatically stop existing billable resources; stop them before suspension.
`closing`	Reserved for asynchronous force-cleanup workflows. Force closure is not available in the current release.
`closed`	Runtime resources and secrets are not recoverable. Retained metadata is non-operational.

Current closure requires no active projects, no outstanding negative balance, and no force flag. It atomically revokes credentials, returns the current eligible paid balance to the parent, expires promotional balance, disables the service principal, and marks the tenant closed. Automated regional force cleanup and final-usage waiting are planned rather than available today. Parent organization deletion is blocked while a non-closed sub-account exists.

Limits and boundaries

Default maximum: 25 active sub-accounts per parent.
Default maximum: 10 active keys per platform parent or tenant.
Tenant records can carry configurable project, spend, and API-rate limits.
IDs are opaque. Store the complete sub_ identifier and never derive meaning from it.
Closed or inaccessible tenants use non-enumerating responses.

Get started

Open Profile → Sub-accounts.
Create a tenant with a meaningful name and your system’s optional external reference.
Fund its wallet from the parent’s paid balance.
Create a machine key and save the one-time secret in a secret manager.
Configure your SDK, CLI profile, or HTTP client and create the first project.

Sub-account API guide

Control-plane endpoints, headers, idempotency, examples, and error behavior.

Product overview

Architecture, applications, coverage, and lifecycle at a glance.