API

Sub-account API

Use parent control-plane credentials to manage tenants, then use tenant-bound or targeted platform credentials against the existing project and resource endpoints.

Integration flow

Create the tenant with a unique idempotency key.
Transfer paid balance into its isolated wallet.
Create a tenant-bound key and store the returned secret once.
Use the existing project and resource endpoints with that key.
Rotate credentials by overlapping keys.
Suspend immediately or close after resource cleanup.

Keep account creation and key creation separate

A retry of tenant creation should return the same tenant without requiring Hubfly space or your application to retain a recoverable plaintext key.

Authentication modes

Credential	Header	Behavior
`hfsk_`	`Authorization: Bearer …`	Tenant is permanently inferred from the credential.
`hfpk_`	Bearer plus `X-HubFly-Subaccount` for resource calls	Parent service principal targets one owned tenant.
`hf_`	`Authorization: Bearer …`	Existing human/PAT access, subject to parent role and project restrictions.

Environment

export HUBFLY_TOKEN="hfsk_…"
# Only for a platform key:
export HUBFLY_SUBACCOUNT="sub_…"

Control-plane endpoints

Operation	Endpoint	Purpose
List/create	`GET /subaccounts` `POST /subaccounts/create`	Discover or provision tenants.
Inspect/update	`GET /subaccounts/:subaccountId`	Read tenant identity, parent, status, and limits.
Lifecycle	`POST …/suspend` `POST …/resume` `POST …/close`	Disable, restore, or retire a tenant.
Wallet	`GET …/wallet` `POST …/wallet/transfers`	Read and fund the isolated balance.
Tenant keys	`GET …/api-keys` `POST …/api-keys/create` `POST …/api-keys/:keyId/revoke`	Rotate tenant-bound machine identities.
Platform keys	`GET /platform/api-keys` `POST /platform/api-keys/create` `POST …/:keyId/revoke`	Manage parent service credentials.

All paths above are relative to https://api.hubfly.space/api/v1. See the endpoint explorer for generated schemas and response shapes.

Create a tenant

curl

curl -X POST https://api.hubfly.space/api/v1/subaccounts/create   -H "Authorization: Bearer $HUBFLY_PLATFORM_TOKEN"   -H "Content-Type: application/json"   -H "Idempotency-Key: tenant-customer-1042-v1"   -d '{"name":"Customer 1042","externalRef":"customer_1042"}'

Create its machine credential

curl

curl -X POST https://api.hubfly.space/api/v1/subaccounts/$SUBACCOUNT_ID/api-keys/create   -H "Authorization: Bearer $HUBFLY_PLATFORM_TOKEN"   -H "Content-Type: application/json"   -d '{"name":"production workload"}'

The returned token is shown once

Write the hfsk_ value directly to your secret manager. Never log it, place it in browser storage, or expect a later list call to return it.

Resource operations

Sub-accounts do not use duplicate resource URLs. Once tenant context is authenticated, call the normal project endpoints.

Tenant key

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

Parent platform key

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

Supported project operations cover containers, builds, deployments, Compose, logs, exec, terminal, tunnels, volumes, file sessions, registry, domains, load balancing, firewall, TLS, redirects, caching, and project networking. Machine credentials are default-denied from personal profile, session, OAuth, PAT creation, invitations, payment methods, and unrelated billing endpoints.

Funding

Transfer USD 25.00

curl -X POST https://api.hubfly.space/api/v1/subaccounts/$SUBACCOUNT_ID/wallet/transfers   -H "Authorization: Bearer $HUBFLY_PLATFORM_TOKEN"   -H "Content-Type: application/json"   -H "Idempotency-Key: funding-customer-1042-2026-08"   -d '{"amountMicroUsd":"25000000","idempotencyKey":"funding-customer-1042-2026-08"}'

Amounts are positive integer strings in micro-USD.
Only paid parent balance transfers; promotional balance does not.
Reuse the same idempotency key only when retrying the same logical transfer.
Do not retry an ambiguous funding failure with a new key until you have read the wallet or reconciled the first request.

SDK and CLI

TypeScript

import { HubflyClient } from "@hubfly/sdk";

const platform = new HubflyClient({ token: process.env.HUBFLY_PLATFORM_TOKEN! });
const created = await platform.subaccounts.create({
  name: "Customer 1042",
  externalRef: "customer_1042",
});

const tenant = new HubflyClient({
  token: process.env.HUBFLY_PLATFORM_TOKEN!,
  subaccountId: created.data.id,
});
const projects = await tenant.projects.list();

Go

platform := hubfly.NewClient(
    hubfly.WithToken(os.Getenv("HUBFLY_PLATFORM_TOKEN")),
)
created, err := platform.Subaccounts.Create(ctx, hubfly.CreateSubaccountParams{
    Name: "Customer 1042",
    ExternalRef: "customer_1042",
})

tenant := hubfly.NewClient(
    hubfly.WithToken(os.Getenv("HUBFLY_PLATFORM_TOKEN")),
    hubfly.WithSubaccount(created.Data.ID),
)
projects, err := tenant.Projects.List(ctx)

With the CLI, an hfsk_ profile needs no tenant flag. A platform key uses --subaccount sub_… or HUBFLY_SUBACCOUNT.

Errors and retries

Status/code	Meaning	Action
`403 SUBACCOUNT_SCOPE`	A tenant key received conflicting tenant context or a platform key targeted outside its parent.	Do not retry; fix credential/header selection.
`403 SUBACCOUNT_SUSPENDED`	The tenant is suspended.	Authorize and resume it after balance/operational review.
`404`	The tenant is absent, closed, foreign, or inaccessible.	Treat as non-enumerating; verify the parent and ID.
`409 API_KEY_LIMIT_REACHED`	The parent or tenant has reached its active credential limit.	Revoke an unused key before creating another.
`409 INSUFFICIENT_BALANCE`	The parent lacks paid balance for the transfer.	Fund the parent or lower the amount.
`400 IDEMPOTENCY_KEY_REQUIRED`	A protected control mutation has no usable idempotency key.	Retry with a stable operation-specific value.

Security checklist

Use a separate key per workload and environment.
Store secrets only in a server-side secret manager.
Never let a customer supply an arbitrary subaccountId without resolving it through your own ownership mapping.
Keep externalRef unique and reconcile it before creating another tenant.
Use stable idempotency keys for creation, funding, and destructive lifecycle actions.
Rotate by overlap: create, deploy, verify last use, revoke.
Alert on cross-tenant denials, revoked-key use, wallet drift, and unexpected API volume.

Platform model

Tenant architecture, permissions, feature coverage, wallet behavior, and lifecycle.

Endpoint explorer

Inspect every sub-account and platform-key request and response schema.