Tenant admins guide

A tenant is the top-level isolation boundary in Arythmatic Connect. One tenant maps to one customer organisation and is anchored by atenant slug (e.g. askmeidentity) which forms part of the URL (askmeidentity.connect.arythmatic.cloud) and the Auth0 organisation.

Inside a tenant you have one or more workspaces (also called Spaces internally) — think of them as separate communities, each with its own feed, channels, members, and theme. Members of the tenant can join multiple workspaces; the tenant slug and tenant admin role are independent of any particular workspace.

The slug is reserved at signup; rename is supported for the display name but the slug itself is sticky to avoid breaking links. A handful of subdomain labels (connect, ops,www, etc.) are reserved at the platform level and can’t be used as tenant slugs.

Tenant admin sidebar → Info. Six fields:

• Display name. Shown in unfurls, the directory, and across the apex marketing pages when your tenant is featured.
• Tagline. One-line description; surfaces in the Discover directory card and on the workspace home for first-time visitors.
• Primary colour. Hex; drives accent in the marketing card. Workspaces can override with industry themes.
• Logo (light + dark). Two variants so the right one renders against light/dark backgrounds.
• OG image. 1200×630 social card used for unfurls of tenant-rooted pages.
• Discovery blurb. Pitch shown in the apex Discover page; up to ~300 chars. This is your sales pitch for cold visitors.

Everything except the slug can be edited any time; changes propagate to the apex Discover page within a few minutes (cache TTL).

Tenant admin sidebar → Listing. Two toggles:

• Publicly listed. When on, your tenant card appears in the Discover directory atconnect.arythmatic.cloud and in the apex sitemap. Cold visitors can find you.
• Discovery priority. Manual curation knob. Higher numbers float to the top of the directory, ties broken by member count then recency. Use this to highlight launches or campaigns.

The directory only lists active tenants (not pending, suspended, or cancelled). Each card links to your tenant subdomain, and signed-in visitors can drop straight in via the join CTA.

By default your tenant lives at <slug>.connect.arythmatic.cloud. You can bring your own — community.yoursite.com, etc. — via Tenant admin → Domains.

1. Add the domain in the admin UI. We show a verification TXT token.
2. At your DNS provider, add a TXT record at_arythmatic-verification.<your-domain> with the value arythmatic-verify=<token>.
3. Add a CNAME record at <your-domain> pointing toedge.connect.arythmatic.cloud (we’ll surface the exact target in the UI).
4. Wait for DNS to propagate (usually seconds, occasionally up to an hour) and click Verify in the admin UI. TLS provisioning is automatic via Let’s Encrypt.
5. Update Auth0 callbacks. Add https://<your-domain>/auth/callback to your tenant’s Auth0 application Allowed Callback URLs and to the Allowed Logout URLs. This step is manual today.

Once verified, CORS, sitemap, RSS, and the embed SDK all serve on the new host automatically. The old subdomain continues working as an alias.

Common pitfall: the most reported “login broken on custom domain” symptom is CORS, not Auth0 — if you can reach /tenants/by-host/ from your browser’s network tab, Auth0 is fine; if not, the CORS allow list hasn’t picked up the new host yet (it auto-refreshes on domain verification but takes a minute).

Tenant admin sidebar → Workspaces. Lists every workspace in the tenant with member count, plan-cap signals (approaching limit / over limit), owner, and creation date.

From this view a tenant admin can:

• Open any workspace directly — bypasses the join flow even for private workspaces. You join as a tenant admin and inherit all moderator privileges via the spaces:update scope bypass.
• Transfer ownership. Pick a new owner from existing workspace members. The previous owner becomes a moderator.
• Archive. Hides from active surfaces; data is preserved and restorable for 90 days. After 90 days the workspace is permanently soft-deleted (still recoverable via a support request for another 90 days, then purged).
• Create a workspace on behalf of someone else, then transfer ownership immediately.

Tenant admin → Members is the tenant-wide CommunityUser directory.

• Filter by tenant role, active status, signup method (Auth0 / embed / invite).
• Change tenant role. admin / moderator / member / guest. Tenant-level role is independent of workspace role; tenant admins get the spaces:update scope which acts as a superuser pass for workspace operations.
• Soft-delete and restore. Soft-delete removes the user from all workspaces and revokes sessions; their authored content stays attributed to the soft-deleted name. Restore available for 30 days from the same admin row.
• Resend activation. If the user signed up via invitation but never confirmed, re-trigger the magic-link email.

Tenant admin → Community invites handles new-member invitations. You can send single invitations (email + tenant role) or bulk-upload a CSV. Auth0’s organisation-invitation API generates the magic link; the tenant’s Auth0 organisation is auto-resolved from the slug.

Permissions in Arythmatic Connect are scope-based. Each role maps to a set of dotted scope strings (spaces:update, tickets:manage,agents:configure, etc.), and views gate on those scopes server-side. The four built-in tenant roles:

• admin — every scope. Functionally a superuser across the tenant.
• moderator — content moderation, ticket triage, workspace help. No billing, no role management, no API keys.
• member — the default. Post, comment, react, join workspaces.
• guest — locked to channels they’re explicitly added to; no feed or directory access.

Tenant admin → Roles is the editor. On Professional tier and above you can mint custom roles with arbitrary scope combinations — useful for “analytics viewer” (just analytics:view) or “billing manager” (just settings:manage). The four system roles are immutable; you can’t delete or rename them.

A frequent tweak: grant a small marketing team analytics:view + analytics:export without making them tenant admins. They get the dashboards and CSV export, nothing else.

Five tiers. Caps that matter most for sizing:

Other things gated by tier (non-exhaustive): the AI “Catch me up” button (Growth+), CSV export of analytics (Growth+), embed SDK (Growth+), SSO (Professional+), audit-log retention beyond 90 days (Professional+).

Tenant admin → Billing. Shows current plan, member / token / paid-channel usage against caps, next renewal date, and a link to the Chargebee hosted page for plan changes.

• Upgrade takes effect immediately. You’re charged the prorated difference for the current period.
• Downgrade takes effect at the next billing cycle. If your current usage exceeds the lower tier’s caps, existing data is preserved but you can’t create new content (e.g. add members) until you’re back under the cap.
• Cancel stops billing at the end of the current period; workspace data is preserved for 90 days post-cancellation, then archived (restorable on request for another 90 days, then permanently purged).
• Invoices & receipts — every past charge with a PDF link. Update the billing email and tax ID under Billing details.

Tenant admin → Payouts wires up payment providers so paid workspaces and paid channels can charge members. Two modes:

• Marketplace. Arythmatic processes payments via our Stripe Connect account. We take a small platform fee; you receive weekly payouts net of fees. Easiest to set up — just an ACH / bank verification.
• Bring-your-own (BYO). Plug in your own Stripe secret key (USD) or Razorpay key (INR). 100% of revenue goes to you; you handle tax compliance and refunds. Use this if you already have a Stripe / Razorpay account.

Currency routing happens automatically based on the paid channel’s currency: USD → Stripe, INR → Razorpay. You can configure both if you want to charge in both currencies.

Tenant admin → Revenue shows lifetime revenue by source (paid workspaces, paid channels), MRR trend, churn rate, and an activations / cancellations breakdown per week.

API keys let external systems (CI, automations, AI agents) authenticate as if they were a tenant member. Mint them at any workspace → Admin → API keys (despite living in a workspace settings page, the key is tenant-wide).

• Format: arc_live_<prefix>_<secret>. The secret is shown once at creation — copy it immediately.
• Auth header:Authorization: Bearer arc_* orX-Api-Key: arc_*.
• Acts as the user who minted the key — the key inherits their tenant role and scopes. Mint with a service-account user if you want narrow permissions.
• Per-call audit log in the integrationsAPIKeyUsageLog table, 90-day retention. Surfaces in Audit logs.

The same keys back the official arythmatic-connect-mcp MCP server. pip install arythmatic-connect-mcp and wire it into Claude Desktop, Claude Code, Cursor, OpenAI Codex, or any other MCP-compatible host. The agent can then read and post on your community programmatically. See the package README for the per-host configuration; the configuration matrix is short, and the MCP can be added in a single command.

The channel-agent feature has two layers:

• Per-channel configuration — owned by workspace moderators (see Moderators guide).
• Operator env — owned by you. Two variables required for Fireworks (the default provider) to work:
  • FIREWORKS_API_KEY — paste your Fireworks AI console key. Token usage is metered per-tenant against the plan cap.
  • AGENTS_ENCRYPTION_KEY — a Fernet key used to encrypt BYO Anthropic keys at rest. Generate once:python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())' — paste the result as the env value. Rotating it invalidates all stored Anthropic keys, so do it deliberately.

Both env vars need to be forwarded through docker-compose if you’re self-hosting — add them to the x-django-env block or whatever your deploy uses. A bare Django setting won’t do it; the worker process needs them too.

The channel-summarization feature is independent of the agents system — it stores per-workspace API keys in the database (encrypted with the same scheme as agent keys) and uses them on demand. There’s no operator env to set; tenant admins or workspace owners paste keys per workspace at Workspace settings → AI.

If a tenant admin wants to operate a centralised model instead (one key for the whole tenant, billed centrally), today they paste the same key into each workspace they want it enabled in. A tenant-level fallback is on the roadmap — let us know if it’s a blocker.

Arythmatic Connect embeds inside iframes for LMS integration. The SDK signs a short-lived JWT with the parent app’s shared secret and posts it to the iframe; the iframe’sEmbedOrAuth0Authentication stack validates the JWT and treats the parent app as the auth source (no Auth0 round-trip).

High-level setup:

1. Tenant admin generates an embed secret under Admin → Integrations → Embed SDK.
2. Parent app (the LMS) installs @arythmatic/embed-sdk, instantiates with the secret + tenant slug, and renders the iframe.
3. On parent-side login, the SDK signs a JWT with the user’s id + email + display name and posts arythmatic:auth to the iframe. The iframe’s EmbedBootstrap persists the token and bypasses Auth0.

Gotchas:

• The JWT must use HS256 (not RS256 — Auth0’s default). The SDK does this correctly; just don’t hand-roll it.
• The embed token is namespaced by X-Embed-Tenant header. One iframe = one tenant.
• Disable the workspace switcher rail in embed mode (the SDK auto- detects this and hides the rail).

Full integration guide ships with the SDK in sdk/INTEGRATION_GUIDE.md.

Available connectors:

• Slack outbound — mirror channel posts to a Slack workspace via incoming webhook. One-way only (Slack messages don’t flow back).
• Webhooks — generic outbound HTTP fan-out (see Moderators guide → Webhooks).
• SSO via SAML / OIDC — Professional tier and above. Wire up via Auth0 (we’ll surface the config UI in Auth0’s dashboard).
• SCIM provisioning — Professional tier. Push users + role changes from your IdP.

Tenant admin → Gamification. Tune the point system that drives the per-workspace + per-tenant leaderboards.

• Per-action point values. Posts, comments, reactions given, reactions received, accepted answers, daily login, profile completion, RSVPing to events, taking a quiz. Default values are sane; tweak if your community has different engagement norms.
• Daily caps per action. Prevent farming. The default cap is generous; lower it if you see gaming.
• Badges. Mint custom badges with an unlock condition (e.g. 100 reactions received) or an explicit grant (admin awards manually). Badges show on member profiles.
• Streaks. Toggle the daily-login streak globally on/off, and configure the multiplier per streak length.

After changing rules, re-run the seed (manage.py backfill_gamification_seed --apply if self-hosting) so existing tenants pick up the new defaults.

Tenant admin → Support queue. Every ticket filed in any workspace of your tenant shows up here so the central support team can triage cross-workspace.

• Filters: by status (open, in-progress, resolved, closed), workspace, assignee.
• Internal comments. Set Internal on a comment for staff-only handoff notes — the reporter doesn’t see them.
• Reassign. Pick any tenant admin or staff member as assignee. The assignee gets a notification.
• Bulk actions. Mark multiple tickets resolved or closed at once. Useful when fixing a tenant-wide issue.

Tenant admin → Audit log. Tenant-wide event stream of security-relevant actions:

• Moderation actions (remove, hide, ban, warn).
• Role + scope changes.
• API key minting, rotation, revocation, per-call use.
• Custom domain verification.
• Plan changes, billing events.
• SSO logins (when SSO is enabled).

Filter by actor, time range, event type. Default retention is 90 days; Professional and Custom tiers get 365 days. Export as CSV or JSON via the icon on the table header.

Two surfaces matter here:

• Per-member export. Any member can request an export of their own data via Account → Privacy → Export my data. They get a download link by email within 24 hours. Tenant admins can also trigger this on behalf of a member via Admin → Members → row menu.
• Per-tenant export. Email support@arythmatic.cloud to request a full tenant export. We’ll ship a JSON archive within 5 business days. Available on every tier.

Right to be forgotten. Per-member soft-delete is available in the admin UI; permanent deletion (purge) requires an email confirmation from the account holder and a 30-day waiting period (cancellable within the window).

If you’re self-hosting (vs running on our managed cloud), the operator playbook covers:

• Docker compose layout, environment variables, secrets management.
• Backup + restore (Postgres + S3-compatible blob storage).
• Upgrade procedure across releases (migrations, beat tasks, frontend deploys).
• Observability hooks (Sentry, OpenTelemetry, log shipping).
• Scaling guidance (worker / beat / WS consumer process counts).

The playbook ships separately to self-hosting customers. Email support@arythmatic.cloud and we’ll send the latest copy.