Use Cases
Platform embedders
A B2B2C product whose end customers own the entities. One portfolio per customer, one scoped key per portfolio, formation in your own chrome, per-customer isolation.
Last updated
A product that offers "form a company" inside its own experience — a business-banking fintech whose customers incorporate before opening an account, a law-firm portal forming client entities at scale, a fund platform spinning up SPVs per deal. Your end customers own the entities; you own the integration. The tenancy pattern is one Portfolio per customer, one portfolio-scoped key per portfolio, and Matter-hosted sessions for the human steps — so customer A's key can never see, read, or touch customer B's companies.
Create
Bring the entity into existence — formation, founder equity, EIN, registered agent.
Onboarding a customer means creating their tenancy boundary before their first entity exists: a portfolio that carries your customer reference, and a key whose blast radius ends at that portfolio's edge.
POST /v1/portfoliosThe portfolio is the per-customer container. Set metadata.customer_id to your own customer reference — the convention for correlating Matter resources back to rows in your database. Every entity the customer ever forms lands inside it.
POST /v1/tokensYour unscoped org key mints a token bound to the customer's portfolio_id. The scoped key creates and operates entities inside that portfolio only; it cannot mint further keys, touch webhooks, or call account-level operations — those return 403 portfolio_scope_denied.
POST /v1/formation_sessionsThe human steps — KYC, signature capture, 83(b) elections — run on a Matter-hosted Formation Session with your branding block (logo, accent color, product name). Your customer never leaves your product's look; you never handle their PII or signatures.
Manage
Operate the live entity — equity programs, board cadence, compliance, qualifications.
Operating an embedded fleet is about routing and proof: each customer's events reach the right handler, and the isolation contract holds under hostile probing — yours and your auditors'.
POST /v1/webhook_endpointsPass portfolio_id when you create the endpoint and it receives only that customer's events — every event payload carries the portfolio it concerned, stamped at emit time, so one endpoint per customer demuxes the firehose with no fan-out logic on your side. Leave portfolio_id off for an org-wide endpoint that sees everything.
Two behaviors define the boundary. Operations outside a scoped key's allowed set fail loudly: 403 portfolio_scope_denied. Resources in other portfolios fail opaquely: 404 not_found, indistinguishable from ids that never existed — a probing customer learns nothing, not even that there was something to learn.
Exit
Wind the entity down — dissolution cascade or M&A envelope.
Offboarding a customer is a revoke plus a handover. One call inventories everything the customer owns; the bytes themselves — a single signed archive the customer downloads — land when object storage ships.
GET /v1/portfolios/{id}/exportOne call returns the complete inventory — every member entity id, a count per resource kind, the portfolio snapshot, and a retrieval pointer per kind into the per-portfolio reads. The customer (or you on their behalf) walks the manifest, pulls each resource, and reconciles against the counts. The single downloadable archive composes on top of this once object storage lands.
POST /v1/tokens/{id}/revokeKill the scoped key first — the customer's integration goes dark immediately while the entities and their records remain intact under your org key.
GET /v1/portfolios/{id}/entitiesDetach members that move to direct management; run the dissolution cascade on the ones being closed.