Billing, API keys and workspace sync

The connection model

Step-by-step billing setup

Billing changes are workspace-level. The safe order is read, choose, checkout, confirm, then re-read. A plan change does not silently create a mailbox, send an email or enroll a contact.

1. 1

   Read the catalogue and current state

   In the UI open Billing. For automation, read both the plan catalogue and the current subscription before choosing a plan.

   Read-only billing preflightCopy

   export API=https://api.vxcloud.io/api/v1/salesshift
   curl -s "$API/billing/plans" -H "Authorization: Bearer $SS_TOKEN"
   curl -s "$API/billing/subscription" -H "Authorization: Bearer $SS_TOKEN"
   curl -s "$API/billing/entitlements" -H "Authorization: Bearer $SS_TOKEN"

   Equivalent vxcli readsCopy

   vxcli salesshift billing plans
   vxcli salesshift billing subscription
   vxcli salesshift billing entitlements

2. 2

   Start checkout or activate a free plan

   Paid plans use hosted checkout. A free plan uses activate. Do not call activate with a paid plan code and do not treat a successful checkout-session creation as a paid subscription yet.

   Hosted checkoutCopy

   curl -s -X POST "$API/billing/checkout" \
     -H "Authorization: Bearer $SS_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"plan_code":"starter","seats":1}'
   
   # Open the returned checkout_url, complete payment, then continue to step 3.

   Free planCopy

   vxcli salesshift billing activate
   # The server refuses a downgrade when an active paid or granted plan exists.

3. 3

   Confirm and inspect the subscription

   After the hosted payment returns, confirm the checkout with its idempotency reference, then read the subscription and event log. The event log is the audit trail when a browser still displays an old status.

   Confirm, then verifyCopy

   curl -s -X POST "$API/billing/checkout/confirm" \
     -H "Authorization: Bearer $SS_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"checkout_id":"chk_…"}'
   
   vxcli salesshift billing subscription
   vxcli salesshift billing events
   vxcli salesshift billing invoices

4. 4

   Use the customer portal for renewal or cancellation

   The portal is the supported place to update cards, download receipts, cancel at period end, or resume a pending cancellation. Re-read subscription after returning from the portal.

   Portal lifecycleCopy

   vxcli salesshift billing portal
   vxcli salesshift billing cancel --at-period-end
   vxcli salesshift billing resume

Create and rotate a developer API key

In the dashboard open Developer → API keys, create a key with a descriptive name and copy it once. For CI, use a separate key per environment and rotate it by creating the replacement before revoking the old one. The raw value is never returned again after creation.

vxcli auth login --username <workspace-user> --api-key xc_live_…
vxcli auth whoami

# Direct exchange used by clients
curl -s -X POST https://api.vxcloud.io/api/v1/auth/developer/keys/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<workspace-user>","api_key":"xc_live_…"}'

• Keep xc_live_* keys in a secret manager or CI secret store.
• Use xc_test_* for sandbox calls where your tenant supports them.
• Do not use AWS, GitHub, Anthropic or OpenAI keys as a VxCloud login key.
• After rotation, run vxcli auth login --force and then vxcli auth validate.

Bind and sync the workspace node

A self-hosted workspace uses a tenant node for crawling, sending and agent execution. The register operation is a handshake: the control plane calls the node over HTTPS and checks that the node reports the same workspace identity. A hostname that resolves but reports a different tenant must be refused.

1. 1

   List the nodes visible to the workspace

   DiscoveryCopy

   vxcli node list
   vxcli node current
   vxcli node refresh

2. 2

   Register the HTTPS node for SalesShift

   Self-hosted registrationCopy

   vxcli salesshift billing node register https://node1.vxcloud.io
   vxcli salesshift billing node
   
   # REST equivalent
   curl -s -X POST "$API/billing/self-hosted/node" \
     -H "Authorization: Bearer $SS_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"host":"https://node1.vxcloud.io"}'

3. 3

   Sync workspace credentials to the node

   Use Sync With Workspace from the node card in VxCloud, or the node sync action in your deployment tooling. The sync writes the node identity, workspace API key reference and configured AI provider references; it does not expose raw provider secrets to the browser.

   Verify after the UI syncCopy

   curl -s https://node1.vxcloud.io/api/v2/health
   curl -s https://node1.vxcloud.io/api/v2/version
   vxcli status

4. 4

   Detach safely when moving a workspace

   Detach only after the replacement node is ready. Detaching stops self-hosted sending, crawling and agent work until another node is registered.

   DetachCopy

   vxcli salesshift billing node detach --yes

CLI and SDK feature coverage

The clients share the same API contract. Use the CLI for interactive operations and CI, the SDKs for application code, and REST for any newly released endpoint before the next client release lands.

A safe client preflight

vxcli auth status
vxcli auth whoami
vxcli node current
vxcli salesshift billing entitlements
vxcli salesshift contacts list --limit 1 --output json

# SDKs load the same credentials written by vxcli
python - <<'PY'
import vxsdk
c = vxsdk.Client.load_from_vxcli()
print(c.salesshift.billing_entitlements())
print(c.salesshift.contacts.list(limit=1))
PY

AI providers and Sales Agent safety

AI drafting is configured per workspace. Store provider credentials in the workspace settings or Vault, select the provider/model in the UI, and run a read-only prompt before enabling any send-capable action. Claude, OpenAI and Ollama are supported provider paths; the exact model catalogue is workspace-dependent.

@sales Read-only preflight: count saved contacts in the USA and return the top three
company names. Do not draft, send, enroll, or modify anything.

• Read-only: list, count, inspect and report. No approval is needed.
• Draft-only: return recipient, subject and body labelled review only, not sent.
• Send-capable: create a pending draft and wait for explicit approval.
• After a send, verify the tracking row and contact audit; do not trust a UI toast alone.

Verification and troubleshooting

For the complete route list see the REST API reference, then use the vxcli reference or the SDK reference for the client equivalent.