API · Tenancy
Portfolios (account-level)
Multi-entity grouping at the account tier — billing, defaults, scoped tokens
Last updated
TL;DR
A Portfolio (pf_…) is the multi-tenancy boundary at the account layer:
billing rolls up to it, registered-agent / signing / tax defaults inherit
downward, and a scoped agent token (tok_…) can target the portfolio
instead of enumerating every entity inside. Multi-tenancy lives in the URL,
not in a header — POST /v1/portfolios/{id}/entities makes it impossible to
accidentally create an entity in the wrong portfolio.
Portfolios are introduced under Create as the formation pattern for venture studios and platforms. This page covers the account-level surface — what a portfolio means at the infrastructure layer rather than the formation layer.
Why this is platform-shaped
Three things make portfolios first-class at the account tier:
- Billing rolls up to the portfolio — invoiced as one line, regardless of how many entities are inside.
- Defaults inherit downward — the portfolio's registered agent, signing chain, and tax-profile template are inherited by every entity it owns unless overridden.
- Scoped tokens target portfolios — a tier-3 token issued to
pf_studio_fund_ican act on every entity it owns without enumerating them. The scope is durable across new entity creation.
Embedded use case
Platforms that want to offer "form a company" inside their product use a portfolio as the multi-tenant boundary:
Platform → owns the API key
Portfolio (per tenant) → defaults + billing + scoped tokens
Entity (per company) → the legal recordEach tenant gets one portfolio. The platform's secret key creates and manages the portfolio. Tenant-facing agent tokens scope to the portfolio.
Related
- Portfolios (Create) — the formation-time view.
- Tokens — scope policies that target portfolios.
- Compliance — portfolio-level deadline rollup.
POST /portfolios