Companies & Users (Admin)
Audience: Support, super-admins, ops · Where in app: /admin/companies, /admin/users, /admin/blocked · Access: Super admins, or admin staff with the Companies / Users / Agencies / System tools sections (see Team & access levels); backend re-checks every endpoint.
These screens are how staff manage tenants. Companies is the primary object (a tenant — owner, subscription, AI credits, feature flags); Users is the people layer (the owner and members, with impersonation); Blocked is the moderation list (block abusive IPs, URLs, or companies). All three reuse the main backend's /company, /user, and /blocked endpoints rather than dedicated admin-only controllers — the admin gate is applied at the route/middleware level.
What it does
- Companies: search/filter every company, view a company's full profile, edit its fields and feature flags, grant manual AI credits / free periods, inspect its AI credit logs and usage, archive, and permanently delete.
- Users: search/filter every user, view/edit a user, delete, and impersonate ("login as") to reproduce a customer's exact session.
- Blocked: create/edit/delete entries that block an IP, URL, or company.
How it works
- The Companies and Users lists are thin admin wrappers over the same backend list endpoints the rest of the app uses (
GET /company,GET /user), passing admin-only filters. Pagination isskip/limit(the FE converts page/pageSize). - Impersonation calls
POST /user/:id/login, which returns a fresh auth token for the target user. The admin then operates as that user. This is the canonical way to debug "it works for me but not for the customer." - Feature flags are toggled via dedicated
PUT /company/:id/<flag>endpoints (one per flag). Most are simple toggles; a few set a numeric allowance. - AI credits are managed via
PUT /company/admin/manual-ai-creditsandPUT /company/admin/free-period. The customer-facing credit balance lives on the company's subscription; every change is audit-logged toai_credit_logs(AICreditLogModel). - Company-name resolution for cost-tracking:
POST /company/admin/names-by-idsresolves a set ofcompany_ids to names — used by the cost-tracking Company Spend tab, sincems-aidoes not store names.
Screens & fields
Companies — list (/admin/companies)
frontend/src/views/admin/companies/List.vue. Search by company name or owner.
Filters:
| Filter | Values | Param |
|---|---|---|
| Status (archived) | Active / Archived | archived |
| Client type | All / Agency / Direct | clientType |
| Subscription type | All / Trial / Active / Canceled (Trial hidden when Agency selected) | subscriptionType |
| Low AI credits | toggle | lowAiCredits |
| Agency | by agency id | agencyId |
Columns: Company, Owner, Agency (hidden for direct), Package, AI Credits, status, and Actions.
Company — detail / edit (/admin/companies/:id, .../edit)
Detail.vue / Edit.vue. View/edit company fields plus feature toggles. Toggle endpoints (frontend/src/repositories/admin/companies.js):
- Identification: Snitcher (
/snitcher+/snitcher-allowed), RB2B (/rb2b), Apollo (/apollo), GDPR protection (/gdpr-protection) - AI inbound/outbound call allowed (
/ai-inbound-call-allowed,/ai-outbound-call-allowed) and per-agent allowances (/ai-inbound-call-agents-allowed,/ai-outbound-call-agents-allowed); SMS / WhatsApp / SDK voice agents allowed (/sms-agents-allowed,/whatsapp-agents-allowed,/sdk-voice-agents-allowed); agent authentication (/ai-agent-authentication-allowed); voice engine (/voice-engine) - Agent K: provider (
/agent-k-provider), queue-status chip (/agent-k-pacing), lab (/agent-k-lab); Nox funnel backfill (the beta toggle was removed 2026-10-09 — the funnel is on per the tenant's own setting) - Webhooks (
/webhooks), Affiliate link (/affiliate-link), Widget whitelabel (/widget-whitelabel), Partner certification (/partner-certification) - Knox memories view/delete (
/knox-memories); company wallet credit (/company/admin/:id/wallet/credit) - Removed 2026-09-25 (
f1d39fb38, now on for every company): Agent K beta, Nox Activity, Nox settings changes, verified visitor badge, widget call/chat GHL tags, chat start URL note. Lead Intelligence / HappierLeads toggles are gone too.
Admin-only credit controls:
- Free period:
PUT /company/admin/free-period(free_period_minutes). - Manual AI credits:
PUT /company/admin/manual-ai-credits(credits_calculation,number_of_credits).
Lifecycle: Archive (GET /company/:id/archive) and permanent delete (DELETE /company/:id — only for archived companies; removes the company and all related data).
Force Logout (5939ffe37, a91e994f1, frontend dca3268d): button on the company detail → ConfirmDialog "Force logout all sessions?" → POST /company/:_id/force-logout (super-admin only). Access tokens are stateless 6-month JWTs, so instead of revoking tokens it stamps users.tokens_valid_from = now on the owner and every member (user_parent.parent_id = owner); the bearer strategy rejects any token issued before it (no extra query — the user is already loaded) and AuthController.refreshToken checks it too (refresh tokens live a year). Second-resolution comparison so a login racing the click survives. Returns "Logged out N users on all devices". Refuses a company with no user_id (400 "Company has no owner") — without that guard the member filter collapses to parent_id: null and logs out every owner and super-admin on the platform. GHL iframe sessions silently re-auth from the stored secret, so a GHL tenant stays out only after go_high_level.secret_key is rotated.
Company — AI Credit Logs (/admin/companies/:id/ai-credit-logs)
AICreditLogs.vue → GET /ai-credit-logs?company_id=.... The audit trail of every credit change (AICreditLogModel, collection-level audit). Each row has source (e.g. ai_tokens_credit_job, manual_ai_credits_job, subscription_renewal, buy_addon, agency_admin_set, admin_override), action (consume / refill / reset / set / addon / override), before/after/delta for remaining_ai_credits and remaining_purchased_ai_credits, consumed_credits, an optional consumption window, and token_usage/metadata. Filterable by source, action, start_date, end_date.
Note: these are customer-facing AI credits (the balance a customer spends), tracked in the main backend — distinct from the provider spend ledger in cost-tracking, which lives in
ms-ai.
Company — AI Usage (/admin/companies/:id/ai-credits-usage)
AiCreditsUsage.vue → GET /admin/companies/:id/ai-credits-usage. Detailed super-admin usage breakdown: summary, by_agent, by_model, paginated raw events, and subscription, over a from/to window.
Users — list (/admin/users)
frontend/src/views/admin/users/List.vue. Search by name or email. Filters: user_type, status. Columns: user, Company, Agency, User Type, Status, plus Actions (Edit opens the edit form, 64c9e1d7). The Impersonate action (handleImpersonate, "Login as this user") calls POST /user/:id/login.
User — detail / edit (/admin/users/:id, .../edit)
Detail.vue / Edit.vue. View/edit user fields — user_type can't be changed (the schema field is immutable since f1f945416; updates drop it) and admins can't be created here (internal people go through Team); a Login as User button (impersonation); shows the user's recent AI credit logs (GET /ai-credit-logs?user_id=...). Delete via DELETE /user/:id.
Agencies — detail (/admin/agencies/:id)
Relevant super-admin levers added 2026-09:
- Min. Wallet Transfer (new sub-account) — inline dollar input (also Opening Wallet Transfer ($) on the agency edit form) →
PUT /agencies/:id { opening_wallet_transfer_credits }(credits, ≥100 = $1.00, else 400). The agency's Add Client form prefills and enforces it; unset agencies use $10. See Managing Companies. - Partner Listing card — take down / restore the agency's Implementation Partners listing (
POST /admin/agencies/:id/partner-listing, with a reason; an owner save can't undo it). - The agency list shows/searches/sorts Owner and Owner Email.
- Add existing company (
3045d15c) moves a direct company under the agency:POST /agencies/admin/:agency_id/companiesatomically takes a paid seat, cancels the company's platform Stripe subscription(s) at period end and re-points the active subscription at an agency package (wallet kept, recurring add-ons and trial flags cleared). If no Stripe cancel succeeds everything rolls back (502). - Client updates is read-only (On / Review first / Off): the agency's own product-update choice (
agency.client_updates.mode). The earlier Announcements (testing) pilot toggle (announcements_pilot) is retired — see Ops workspace.
Moderation — Blocked List
/admin/blocked, .../create, .../:id/edit (frontend/src/views/admin/blocked/*, repo blocked.js). Block one of three types (BLOCKED_TYPE): ip, url, company. Endpoints: GET /blocked (filter by type, search), GET /blocked/:id, POST /blocked, PUT /blocked/:id, DELETE /blocked/:id. This is the entry point for shutting down abusive traffic or a bad actor company.
Behaviors & edge cases
- Force logout ≠ block. It ends current sessions only; the users can log straight back in. Block the users (or rotate the GHL secret for iframe tenants) to keep them out.
- Impersonation is full takeover.
POST /user/:id/loginissues a real token for the target user — anything you do is done as them. Use it for support repro, and be deliberate about side effects (do not send messages / change settings as the customer unless intended). - Permanent delete is destructive and gated.
DELETE /company/:idremoves the company and all related data; the flow expects the company to be archived first.DELETE /user/:idremoves the user. Neither is reversible. Archived companies can also be deleted automatically after a grace period (Admin → Settings → Archived Account Deletion, off by default) — see Admin Settings. - Manual AI credits bypass the normal billing path — they write directly to the subscription's credit balance and are logged with an admin source (
admin_override/manual_ai_credits_job/agency_admin_set). Use the AI Credit Logs screen to see who changed what. - Feature toggles are per-company and take effect immediately; "allowed" variants set a numeric cap rather than a boolean.
- Filters interact: selecting Agency client type hides the Trial subscription filter (and clears it if it was set), because agency subscriptions don't model trials the same way.
- Two different "credits". Customer AI credits (this cluster, main backend) ≠ provider cost credits (cost-tracking,
ms-ai, 1 credit = $0.01). Don't conflate them.
Technical implementation
- Frontend views:
frontend/src/views/admin/companies/*,frontend/src/views/admin/users/*,frontend/src/views/admin/blocked/* - Frontend repos:
frontend/src/repositories/admin/companies.js,users.js,blocked.js - Backend endpoints:
/company*(incl.POST /company/:_id/force-logout),/user*,/blocked*,/agencies/:id,/admin/agencies/:id/partner-listing,/ai-credit-logs,/admin/companies/:id/ai-credits-usage,/company/admin/{names-by-ids,free-period,manual-ai-credits} - Models:
AICreditLogModel(ai_credit_logs), plus Company/User/Subscription models - Related service: ../services/backend.md
Related
- overview.md — admin portal index
- revenue.md — subscription revenue
- cost-tracking.md — AI provider spend (separate "credit" concept)
- ../subsystems/identity-graph.md