Agentfy for platforms: organizations, owners and payers
Design specification · AGNT2-424
Documentation only; the partner API, organizations, account links and payer assignments below are not implemented. This replaces the AGNT2-423 proposal. Confirmed product decisions are separated from recommended technical defaults; implementation must pass the release gates in the audit and migration plan.
A person registering directly gets a team in the default Agentfy organization and is its owner and initial responsible payer. BONSITE can prepare a customer's team with only stable external identifiers, before that customer first visits. BONSITE pays by default; organization-paid and team-paid teams both belong in v1. Changing the owner or payer never changes the team's organization.
Naming convention (approved)
Organization is the entity name and organizationId is its model field. The canonical API resource segment is orgs: /v1/orgs/{orgId}, where orgId is the path parameter for that organization. “Partner” describes a business role or integration (for example, BONSITE as a reseller), not another organization resource namespace. Identity issuer, external subject and partner-origin authentication remain distinct technical concepts.
Confirmed product decisions
- Agentfy is the default organization, not a platform administrator shortcut. Its independently registered private teams cannot discover one another.
- BONSITE owns its login experience and server credentials. It need not send an email, name or password. User IDs and team IDs are separate: users can join several teams and teams can have several users.
- Direct signup makes its creator an owner; server bootstrap records the service in
createdByaudit and the designated external actor as initial owner, never the key; another person accepts payment responsibility before it transfers. Organization coverage can be authorized by an administrator. Agentfy covering its own team is internal sponsorship, not an invoice to itself. - Customer team membership does not grant organization membership. Organization members are partner operators; API keys are service principals, never fictional human owners.
- Partner users may stay entirely inside BONSITE, open the Agentfy interface, or connect an independently authenticated direct account. Matching email is never identity proof.
Recommended architecture
Use stable resource actors and explicit account links. A direct User and a partner-scoped User remain different records. ExternalIdentity(namespace, externalUserId) identifies the partner actor; AccountLink lets one independently authenticated direct account deliberately activate that actor's context. It does not rewrite memberships, agent ownership, invoices or historical events.
A canonical-user merge would reduce records but makes every existing userId → teams lookup a potential privilege escalation. Safely merging would require provenance on every grant and an extensive authorization rewrite. Separate actors keep the current ownership keys meaningful and make unlink reversible. This is the selected design recommendation, not an implemented database schema.
Organization Agentfy ─ direct team ─ UserTeam(owner: direct User D)
Organization BONSITE ─ partner team ─ UserTeam(owner: partner User P)
immutable namespace + externalUserId ─ ExternalIdentity ─ P
D ─ AccountLink ─ P (no ownership rewrite)
Team ─ effective-dated PayerAssignment ─ BillingAccount| Term | Meaning and invariant |
|---|---|
| Organization | Administrative and integration scope; exactly one per team. No cross-organization team moves or nested resellers in v1. |
| Namespace | Immutable organization + environment identity scope. Test and production credentials, subjects, redirects and resources are isolated. Renaming BONSITE does not rename its namespace. |
| User | Stable authorization/ownership actor. Direct users have direct credentials; partner actors belong to one namespace and need no email. |
| Login method | Proof for a direct account or partner subject, not a membership or payer. Partner credentials cannot recover direct credentials. |
| ExternalIdentity | Permanent unique namespace + opaque subject mapping to exactly one partner actor, including tombstones. Never recycle a deleted subject. |
| AccountLink | One active direct account per external subject; a direct account may link several subjects. No transitive traversal, automatic email matching or union of grants. |
| UserTeam | Unique actor + team membership; role owner/admin/member. Several owners are valid. No competing Team.ownerUserId. |
| OrganizationMember | Operator role, independently assigned. Customer membership and organization ownership are distinct. |
| BillingAccount | Responsible direct user or organization. A billing contact is only a notification destination. |
| PayerAssignment | Exactly one effective assignment per team at a time, with disjoint half-open intervals and immutable history. Free entitlement can exist without a paid mandate. |
| Customer label | Optional externalCustomerId, reporting only; it confers no authority or liability. |
| Visitor | Guest embed participant, not a team member; current owner-executing embed remains a separate product boundary. |
Internal and external IDs are immutable. External team IDs are unique within namespace, independently of user IDs; agent external IDs are unique within a team. Permanent mappings survive operation-receipt expiry. Deleted resource IDs stay reserved. Team data is shared according to team permissions; agent ownership does not create private space within a shared team.
Access and trust
A partner-origin session can act only as its partner actor in its namespace and current active membership. Even after linking it cannot enter direct/private/other-partner teams, list other links, change direct credentials, use personal payment methods or acquire a platform role. A direct login can explicitly enter a linked context only while the link, subject, organization policy and membership remain active. Every action records actual authenticating account (when present), effective actor, source, organization, team and delegation/credential ID.
BONSITE is trusted to authenticate its own subjects. An issuer able to assert arbitrary BONSITE subjects can impersonate those subjects and therefore access their team content. Separate scopes prevent an ordinary provisioning or billing key from doing this, but do not make customer content secret from a malicious identity issuer or an operator allowed to issue identity credentials. Privacy from BONSITE itself would require independent user-held proof and is outside v1. The boundary that must hold even against a malicious issuer is isolation from linked direct accounts and other namespaces.
| Principal/role | Explicitly permitted | Not implied |
|---|---|---|
| Organization owner | Activation/closure, operator roles, billing agreement; separately confirmed privileged identity-issuer administration | Platform role or direct-account access |
| Organization admin | Own-organization team lifecycle and approved grants; coverage only with billing delegation | Conversation/secret routes; identity issuance by ordinary admin key |
| Organization developer | Scoped provisioning, operation diagnostics, inline agent profiles | Billing consent, role escalation, browser authorization by provisioning key |
| Organization billing | Organization invoices, totals, payer approval and billing contacts | Chat text, secrets, team membership |
| Organization support | Sanitized diagnostics; time-limited delegated content access if explicitly granted | Standing impersonation or raw conversations |
| Team owner | Team settings, invitations, owner transfer, payer-change request, deletion | Organization role or another person's financial consent |
| Team admin | Member invitations/administration within policy, team operations | Owner demotion/transfer, payer consent, team deletion |
| Team member | Granted team data and agent actions | Membership administration or billing control |
| Responsible payer | Own mandate, bills, acceptance/termination of future liability | Team content or ownership; membership is optional |
| Service principal | Exact namespace + endpoint scopes; provisioning is separate from identity issuance | Human owner, direct login, platform access |
| Platform administrator | Separately authenticated, audited intervention and recovery; scoped reason and expiry for content support | Authority from organizationId=Agentfy |
Default deny applies beyond controllers: jobs, sockets, search, exports, storage, signed downloads and cache keys recheck organization/team/actor. Team IDs in payloads grant nothing; foreign resource failures are nondisclosing 404s. Payer changes grant no membership or data access; ownership changes grant the target team role only, never organization/global/other-team rights. Partner actors cannot be added to foreign-namespace teams; v1 customer memberships in a partner organization require that organization’s external actor. Direct customer accounts enter through AccountLink only; direct invitations apply to Agentfy teams. Organization operators use explicit scoped delegation. This prevents an external owner inviting their direct account to bypass partner deprovisioning.
Reading order
- Identity and user journeys: screens, browser protocol, linking, ownership and lifecycle.
- Provisioning and payer contract: proposed requests, retries, scopes and financial cutovers.
- Migration and self-audit: current-code evidence, adversarial walkthrough and release gates.
Current billing and current guest embedding describe shipped behavior, not these proposed guarantees.