Partner identity and complete user journeys

AGNT2-532: Free. Billing is not connected yet. No contract, contract budget, card or redirect URI is required to create, activate or provision an organization. Usage does not create debt or future payment obligations. Resource limits, approved policies, operator permissions and explicit platform activation still apply. Future paid usage requires separate opt-in; free-period usage must never be billed retroactively.

Historical design snapshot

This page records the earlier design scope, not current release status. Agentfy now has committed provisioning, scoped authorization and trusted MCP foundations; see the implemented server-chat contract and evidence boundary. Browser/BONSITE protocols and broader billing/lifecycle proposals below retain their own release gates. No live partner deployment is implied.

1. Direct registration

On Create an Agentfy account, a person verifies their direct email/login proof and chooses credentials. The confirmation says “Create my team; I am responsible for its billing.” A free plan does not authorize charges: paid work still requires a valid mandate and budget. Commit direct user, initial Agentfy team, owner membership, initial responsible-payer assignment and provisioning operation together; then show Preparing your assistant, Open team, or Setup failed — retry. Retrying uses the same operation, not another team or charge.

Direct signup is distinct from the credential-only flow in section 5. An existing direct account signs in instead of claiming a passwordless user merely because the email matches. Legacy invitation stubs require verified invitation acceptance and migration treatment; partner signup must never use the current email-stub claim or platform-founder path.

2. Organization onboarding and keys

Free. Billing is not connected yet. No contract, contract budget, card or redirect URI is required to create, activate or provision an organization. Usage does not create debt or future payment obligations. Resource limits, approved policies, operator permissions and explicit platform activation still apply. Future paid usage requires separate opt-in; free-period usage must never be billed retroactively.

Integration → Server credentials shows scopes, environment, expiry and last use. Create provisioning key displays its secret once; only a hash is retained. Store the secret on BONSITE's server. Browser identity authorization uses a separate identity-issuer credential, privileged approval and audit trail. An ordinary developer can rotate delegated provisioning credentials but cannot add identity issuance to them. Record issuer, createdAt, expiresAt, revokedAt and credential version; never infer revocation from deletion alone.

Recommended defaults: keys expire after 90 days, planned rotation overlaps at most 24 hours, emergency revoke has no overlap. New key retries use the same organization-scoped operation records. Revoking an issuance key revokes sessions derived from it; provisioning-key rotation does not delete users or revoke unrelated direct sessions. Closing/suspending the organization blocks new issuance and partner-context use. Every code, proof, link and derived session records issuer credential and organization auth epoch. Revoke invalidates pending code/link completion. For a compromised identity issuer, increment the auth epoch and quarantine links/proofs from the suspected compromise interval; restore them only after new independent proofs or audited recovery. Routine rotation does not erase legitimate links, owners or history.

3. BONSITE signup and workspace bootstrap

BONSITE authenticates its own person and derives opaque externalUserId from its server session. It can also prepare a team before a human visits, using a server-known stable subject. Never accept a browser's claimed subject without BONSITE authorization; never create a fake email or a shared owner user.

BONSITE submits a stable external team ID and creator subject. Agentfy atomically resolves/creates that actor, team, owner membership, payer assignment and durable operation. Default payer is the organization. For team-paid mode, request a previously accepted team-specific direct-payer consent, or create a free/pending-billing team with the creator's responsibility recorded and paid work disabled until independent direct consent. A key cannot agree to a person's debt. The team does not change organization when that consent is completed.

The customer sees Preparing assistant, then Open assistant, or Setup interrupted — retry with a safe support reference. Existing identity/new team is allowed. Existing team/same original bootstrap returns the operation and current readiness without regranting a removed creator or overwriting current ownership/payer. Different bootstrap facts for the same external team yield an explicit conflict; use separate authorized membership or billing flows for changes. A foreign/mismatched resource receives “Workspace unavailable,” without confirming another tenant exists.

4. Open in Agentfy: browser authorization

Open in Agentfy starts a transaction on Agentfy's own origin; a link from BONSITE is only an entry point, never an identity assertion. Prefer a reviewed OAuth authorization-code/OIDC integration when BONSITE supports it. The custom protocol below is a proposed alternative, not an OIDC compliance claim.

1. Agentfy creates a purpose-specific transaction (login, link, or invite), random state/nonce, PKCE S256 challenge/verifier where authorization-code exchange is used, and a Secure, HttpOnly browser-binding cookie. Store transaction hash, exact redirect URI, organization/environment, intended resource and expiry server-side. Browser entry without a matching transaction cannot sign anyone in.
2. Redirect only to BONSITE's registered authorization endpoint. BONSITE authenticates the person, verifies workspace rights and confirms “Continue to Agentfy as [BONSITE account]?” Its identity backend proves the subject over an authenticated backchannel bound to transaction ID, nonce, purpose, audience, environment and expiry. A provisioning key is refused here. The first accepted proof freezes subject and purpose; a conflicting retry is rejected. There is at most one redeemable code/session result per transaction, including callback reissue.
3. Agentfy creates a random one-use code, stores only its hash and binds it to that transaction and proof. Return it through the registered callback using a POST where possible; no access/refresh bearer token goes in URLs, logs or browser storage. If an authorization code crosses a query string, redact it from logs/referrers, use Referrer-Policy: no-referrer, remove it immediately and load no third-party assets on the callback.
4. Agentfy verifies browser binding, state, nonce, proof, exact redirect and PKCE verifier where applicable. In one transaction, compare-and-set unused/unexpired code to consumed, recheck subject/org/membership, and create a restricted session. Replay and races have exactly one winner; failures do not create sessions.
5. Show the target organization/team and Continue in BONSITE context. If a different direct account is already signed in, do not replace it or link automatically: offer Continue in separate partner context, Choose another account, Cancel. Linking needs section 5's fresh proofs and separate confirmation.

Each tab has a distinct transaction and context handle; changing context in one tab must not silently change another tab's request authority. Bind mutating requests to their explicit server-side context, check Origin/CSRF tokens, and reject stale-context forms with “Context changed; reload before saving.” Cancel/expiry consumes or invalidates the transaction; retry starts a new one. A leaked code, invitation URL or unsolicited attacker login link lacks browser binding and fresh proof and cannot authenticate its recipient.

Proposed defaults: browser transaction 5 minutes, one-use code 60 seconds, fresh authentication within 5 minutes for linking, unlinking, owner/payer transfer and credential changes; partner access session 5 minutes with rotating server-managed refresh family, 30-minute idle and 12-hour absolute lifetime. Direct sessions and partner sessions have separate families. These are design targets, not measured runtime properties.

Cookies use Secure/HttpOnly and the strictest SameSite compatible with the chosen callback (normally Lax; cross-site POST support requires an explicit CSRF-safe design). Never persist bearer tokens in local/session storage. Validate issuer, audience, type, signature algorithm, time, source, session family and authorization versions. Distinguish direct-user, partner-restricted, runtime-worker and guest-embed tokens; no refresh or token exchange may widen the original source or scopes. Standard user APIs reject partner tokens unless the endpoint explicitly supports the restricted principal.

5. Add direct login or link an existing account

In the partner context, Account → Connect Agentfy login offers Create a direct login and Use my existing account. Explain: “This connects access to your BONSITE workspace. It does not move your team, change its owner or payer, or let BONSITE into your other teams.” Show organization and recognizable partner account label without requiring BONSITE to supply personal data.

For a new login, collect and verify credentials on Agentfy, outside partner APIs. Create a direct actor without automatic team/concierge creation, then link it to the existing partner actor. For an existing login, require fresh direct authentication in addition to fresh BONSITE proof; email coincidence, an old cookie or possession of the partner key is insufficient. If the email already belongs to an account, require signing into/recovering it; do not create a duplicate or silently claim it.

The confirmation shows the direct account only to that independently authenticated browser: Connect [direct account] to [BONSITE context]. Commit the link only if both proofs remain valid, the subject and org are active, policy allows linking, and no other active link exists. Lock the external-subject/link row; a unique active-subject constraint resolves concurrent confirmations. Same account/same transaction retry returns its existing result. A subject already linked elsewhere returns “Already connected; disconnect or recover the original connection,” without disclosing that account to BONSITE. The partner cannot relink it unilaterally.

Creating credentials and the first link is atomic locally. If an external credential provider succeeds but the final link fails, leave an independently usable empty direct account and show the conflict; never create a team as compensation or delete existing credentials. Expired proofs restart confirmation. No membership, owner, agent ID, debt or ledger record changes when linking.

6. Context switching and unlink

After direct login, Workspaces separates My Agentfy teams from named linked partner contexts. Selecting BONSITE checks the active link, active partner subject, organization policy, team status and active membership. Effective actor becomes the partner user, with the direct account recorded as authenticator; permissions are not combined. Returning to direct context uses the independent direct session. Partner-origin login never gains that return path unless a separately authenticated direct session exists, and cannot enumerate its teams or links.

Recommended policy fields are allowNewLinks and allowLinkedLogin. Turning off new links preserves existing linked access; turning off linked login invalidates all derived linked contexts but retains link records for explicit re-enable. Partner subject deprovision blocks linked access regardless of direct-account status. Re-enable does not restore revoked memberships or session families.

Disconnect BONSITE requires fresh independent direct authentication and shows: “Your BONSITE team and bills remain. Use BONSITE to access it.” Revoke the link, its pending transactions and every session/context derived from it, including refresh families; separately established BONSITE-origin sessions may continue if that subject remains active. Do not revoke unrelated direct sessions, move ownership or forgive debt. Relink requires two new proofs; old codes and refresh tokens remain invalid. Partner identity revocation can invalidate its link-derived access but cannot mutate the direct account or its credentials.

Removing the last direct login method is blocked until another independently verified method is added, or the person uses explicit account deletion. Direct-account deletion revokes direct sessions and links; partner users and their teams survive. Its own direct-team ownership and unpaid billing require transfer/retention handling, not cascade deletion. Direct credential recovery uses Agentfy's independently verified recovery channel, never a partner key. Losing BONSITE access cannot be bypassed by a link. Support recovery is a separately authorized, audited identity-verification procedure; if proof cannot be established, access stays blocked.

7. Membership invitations and owner transfer

Team → Members → Invite chooses a role and permitted target actor type: only same-organization external actors for BONSITE customer teams, only direct actors for default Agentfy teams. A partner owner cannot invite their direct account to bypass external-subject revocation. A partner invite addresses a namespace + stable subject; a direct invite addresses a verified direct account or a single-use invitation completed after independent login. Email is a delivery address, not permission to claim a partner subject. Invitation records bind team, target, role, inviter, version, expiry (recommended 7 days) and consumed state. The acceptance screen names organization/team and role, with Accept / Decline; preview reveals no chats/secrets. Recheck inviter authority, target proof, team status and current policy at acceptance. A forwarded invite or matching email cannot change the target actor. Invite redemption and membership creation are atomic and idempotent; revoked/expired invitations show Ask for a new invitation.

Team admins cannot invite/promote owners; owners can propose owner promotion or transfer to an existing active member. Transfer ownership names the recipient, affected agents and the outgoing owner's resulting role. Recipient accepts under its eligible context and fresh proof; a direct recipient in an Agentfy team requires direct login; a BONSITE recipient is that namespace’s external actor. Under a team lock/version check, add/confirm recipient owner before demoting the initiating owner. Other owners remain owners. Cancel/decline/expiry leaves roles unchanged. Ownership transfer never transfers billing.

At least one active owner is required for an operational team. Voluntary last-owner removal/demotion is blocked transactionally, including concurrent requests. Before removing/deactivating any actor, enumerate agents owned through Agent(ownerId, teamId) and explicitly reassign them to an eligible active member with confirmation, or suspend them and retain the inactive membership tombstone. Never orphan schedules or silently select an arbitrary remaining member. Agent reassignment does not expose private user-scoped secrets; revoke/reconfigure dependent grants before resume.

8. Suspension, deletion and recovery

Security suspension always wins over the last-owner rule. If a revoked partner subject was the last active owner, suspend the team and its work, keep ownership evidence, and require explicit recovery/owner appointment through an audited authorized flow. Do not refuse revocation and do not auto-promote a member.

Event	Immediate effect	Recovery / retained state
Partner subject suspended/deprovisioned	Deny partner and linked contexts; revoke sessions/invites; suspend affected automation pending reassignment	Restore same subject only after explicit verification; revoked memberships require a new grant; external ID never reused
Direct account suspended/deleted	Deny direct and link-derived contexts; resolve direct ownership/payer obligations	Partner actors survive; independent BONSITE login can continue; retention of financial evidence
Team suspended	Deny work, membership acceptance and new grants; revoke team contexts	Authorized resume rechecks owners, agents, grants and payer; no automatic job replay
Team deleted	Tombstone external IDs, revoke keys/invites, stop jobs and arrange provider cancellation	Authorized data export before deletion; retain financial/audit evidence; no resurrection via bootstrap retry
Organization suspended/closed	Deny issuance and all its team execution, including linked contexts and operator delegations	Other organizations/direct teams remain usable; closure retains namespace, financial history and tombstones
BONSITE unavailable/ceases operation	No partner proof possible; existing direct-linked access only while org/subject policy remains active	No silent move to Agentfy; separately approved contractual export/transition, otherwise suspend and resolve billing
Sponsor/payment mandate removed	Stop new paid reservations at effective cutoff	Free plan within existing entitlement may continue; no automatic charge to team owner; payer consent required

BONSITE sends authenticated, retryable lifecycle updates with monotonically increasing subject revision; Agentfy durably acknowledges before reporting success. A stale activation cannot undo a newer suspension. Proposed freshness contract: reconcile at least every 5 minutes and require a partner-status lease no older than 15 minutes for every partner/linked action. During an outage, access stops when the lease expires; fresh login proof alone cannot override a known suspension. The lease is per external subject, renewed only by a fresh authenticated reconciliation for that subject. An organization heartbeat or duplicate/stale lifecycle event cannot advance confirmedAt or extend the lease. The revocation SLA starts when Agentfy accepts the revocation, not at an upstream change it has not received.

Revocations are checked against authoritative state at each new action, refresh, download authorization and job dispatch; unavailable authorization state fails closed. In-flight streams/sockets are invalidated and cancellation is targeted within 60 seconds, measured under load before release. Existing external effects cannot be undone; record actual incurred usage. Download capabilities must expire within the same bound or pass a revocation-aware proxy. Explicit resume reauthorizes work instead of replaying stale queued jobs. Audit records contain identifiers and reason, never raw tokens or secrets.

Security grounding

Proof of both accounts follows the principle described in Auth0's account-linking guidance; this design does not adopt its global merge semantics. Exact redirect checking, PKCE and login-CSRF defenses are grounded in RFC 9700. Stable issuer/subject identity rather than email follows OpenID Connect Core. The protocols, defaults and isolation model above are Agentfy design recommendations requiring implementation review.