Topolo Docs Topolo Platform
Open workspace

Complete Suite signup

Prepare the verified checkout organization, included apps and owner login, with idempotent billing ownership binding.

Prepare the verified checkout organization, included apps and owner login, with idempotent billing ownership binding.

Action app_topolo_one.signup.provision · POST /api/signup/provision. Intended audience: public.

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=False, agentAccess=confirm. HTTP method and empty permission fields do not override the actual effects or authority below.

Authority and prerequisites

  • Declared authorization mode=public, requiredPermission=empty; actual source identity/resource checks below remain mandatory.
  • Discover the actual identifier and current intended state within existing authority. Examples grant no access and are not executable probes.

Identifiers

  • Use the original sessionId and matching unexpired handoff. Retain resulting orgId securely and reconcile retries against that exact checkout; no other person’s account or grant may be substituted.

Input

  • sessionId: type="string"; pattern="^cs_[A-Za-z0-9_]{1,190}$". Required.
  • handoffToken: type="string"; pattern="^\d{1,10}\.[a-f0-9]{64}$". Required.

The exact native input/output schemas are retained in the hidden paired layer for this version. Top-level undeclared fields are rejected. Nested open records and semantic prerequisites still need source checks.

Effects and important boundaries

  • Verifies the original checkout subscription and purchased plan capacity, provisions its buyer organization and included apps, then binds billing ownership.
  • Returns a protected owner login credential with the canonical TopoloOne callback. Caller-supplied owner IDs, apps and redirects are not accepted.
  • These are the marketing signup actions, distinct from the older app_topolo_one.checkout.create/quote guides. Do not overwrite or rename those existing records.
  • Catalog-public transport is protected by business/human prerequisites. The checkout handoff is a secret origin-and-session-bound HMAC credential, valid only until its expiry (maximum 24 hours), not an unrestricted user/org grant.
  • The examples contain unusable synthetic tokens and session IDs. They demonstrate schema shape only; no token was generated, no buyer was queried, and no account/trial/checkout/charge/grant was created.
  • Protect checkout handoff and owner login credentials; never put real values in general documentation, logs or a shareable receipt.
  • Verifies the original checkout and purchased capacity, provisions its buyer organization/included apps, and binds billing ownership idempotently. This has access and financial-state effects even though no direct card charge is requested by this route.
  • The wrapper fixes app_topolo_one and the canonical One /auth/callback. Caller owner/app/redirect overrides are not accepted. It validates the returned Auth login origin and extracts the protected login token.
  • The first subscription-status check admits trialing, active and past_due and refuses other states with 402 SUBSCRIPTION_NOT_ACTIVE. Suite signup then applies a stricter guard: only active or trialing with valid human-seat capacity is eligible; a trial must have an unexpired trial end. A past_due Suite subscription is refused with 422 INVALID_HUMAN_SEAT_SUBSCRIPTION. Passing the initial check does not establish eligibility.
  • A downstream binding/login failure can follow earlier provisioning effects. No destructive automatic rollback is available. Preserve the original session and use its existing billing/access recovery owner instead of deleting the organization to retry.

Refusals, failures and recovery

  • 403 CHECKOUT_SIGN_IN_REQUIRED: Use the protected handoffToken returned by this checkout on the same environment and site. A checkout URL or session ID alone is not buyer authority. Start a new checkout if the credential expired.
  • 400 VALIDATION_ERROR: Correct only the schema-invalid input. Keep the original protected token and session ID together.
  • 404 NO_SUBSCRIPTION: Read the original checkout until its verified subscription exists; do not create a duplicate checkout.
  • 403 EXISTING_ACCOUNT_SIGN_IN_REQUIRED: Sign in to the existing account and use its organization management flow. The checkout handoff cannot take over an existing email identity.
  • 409 CHECKOUT_IDENTITY_CONFLICT: Keep the original checkout buyer identity. Recover that checkout through billing rather than changing its buyer or creating duplicate organizations.
  • 422 INVALID_HUMAN_SEAT_SUBSCRIPTION: Recover the original subscription through billing. Invalid or expired capacity cannot provision a Suite.
  • 503 PROVISIONING_UNAVAILABLE: Retry the same session and protected token after the temporary service failure. Existing organization provisioning is idempotent.
  • 402 SUBSCRIPTION_NOT_ACTIVE: The subscription failed the initial status guard. Reconcile the original checkout; a record alone does not authorize provisioning.

No destructive automatic rollback is available for a paid signup. Preserve the original session and use billing recovery; never delete its organization to retry.

Verification

  • Confirm the resulting organization ID matches a retry of the same checkout.
  • Use the returned protected login only for the canonical Auth consume URL and verify the included app catalog as the new owner.
  • Retain actual request/receipt identifiers securely, preserve UNKNOWN effects and reconcile before any retry.

Run a reviewed request

Discover the current action and its resource requirements before running it. Save the approved input as reviewed-input.json; replace synthetic examples with values obtained through the intended authorized workflow. If discovery requires a resource binding, provide its published type and resolved ID separately on both plan and call. Stop if validation fails or the plan is not executable.

topolo actions get app_topolo_one.signup.provision --json
topolo actions validate app_topolo_one.signup.provision --data @reviewed-input.json --json
topolo actions plan app_topolo_one.signup.provision --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_one.signup.provision --data @reviewed-input.json --confirm --json

--confirm must represent approval of the actual request and its effects. The examples do not supply that approval.

For local CLI/MCP secret outputs, pass the protected topolo-secret: reference unchanged; do not extract the underlying checkout or login credential into a file or log.

Worked examples

All examples are synthetic and unrun. They cannot authorize access, create human consent, prove media/provider success or establish financial/customer state. Placeholder tokens are unusable. No contact, payment, notification, provisioning or business read was executed.

Organization result excerpt

SOURCE-AUTHORED SYNTHETIC, UNRUN. Partial excerpt; not a complete response. Output assessment: PARTIAL_EXCERPT_NOT_COMPLETE_SCHEMA.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "success": true,
  "orgId": "org_example"
}

Partial hypothetical response; live loginUrl/loginToken are intentionally not fabricated. No organization was provisioned.

Refusal or failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Source-derived error-code excerpt only; messages/envelope can differ by layer or locale. Not a captured response. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "error": "CHECKOUT_SIGN_IN_REQUIRED"
}

No valid session handoff means no authorized provisioning.

Invalid input: stop at schema validation

SOURCE-AUTHORED SYNTHETIC, UNRUN. null is a no-response sentinel, not returned JSON null. Output assessment: NOT_APPLICABLE_NO_REQUEST.

Input:

{
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

null

Intentionally invalid input; no request was issued and no HTTP response/status is asserted.

Boundary: existing but non-provisionable subscription

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "success": false,
  "code": "SUBSCRIPTION_NOT_ACTIVE"
}

402 for a source-refused subscription status; mere record presence is insufficient. This source refusal is additional to the current catalog error list.

Source and verification limits

Reviewed against cb18601dad6735f8140a4c81e9650d9fc3599f9a at apps/marketing/worker/signup-action-routes.js and the published action schema on 2026-10-20. Examples are synthetic and unrun. Source review and schema validation do not prove current deployed behavior, provider completion or business delivery. Response excerpts are labelled where incomplete.

Change log

  • 2026-10-20: Prepared the action guide with paired agent schemas, permission and effect boundaries, worked examples, verification and recovery instructions. Independently checked the pinned source; publication and runtime verification remain separate.