Admin API

Complete reference for the super admin GraphQL API. All operations require a valid JWT token and isSuperAdmin: true on the authenticated user.

Total operations: 57 (32 queries, 24 mutations, 1 subscription)

warning

All admin endpoints are protected by JwtAuthGuard + SuperAdminGuard. Non-superadmin users receive a ForbiddenException (403).

Authentication

Every request must include:

Authorization: Bearer <jwt-token>

Platform Analytics (15 Queries)

Query	Description
`adminPlatformOverview`	Consolidated stats: users, companies, jobs, candidates, talents, MRR, active subscriptions
`adminUserStatistics`	Signup trends (30 days), status breakdown (verified/unverified/superadmins), auth method split
`adminCompanyStatistics`	Growth trends, size distribution, industry breakdown, avg users per company
`adminRevenueStatistics`	MRR, subscriptions by status/plan, invoice summary, promo code impact
`adminRecruitmentStatistics`	Jobs by status, candidates by status, conversion funnel with rates
`adminMeetingStatistics`	Meetings by status/type, interview scores, completion/cancellation rates
`adminNotificationStatistics`	Delivery rates, engagement (read/click rates), channel breakdown
`adminTalentPoolStatistics`	Pool status breakdown, CV parse stats, skills distribution
`adminCollaboratorStatistics`	Invitation acceptance rate, shares by type, collaboration trends
`adminOnboardingStatistics`	Employer vs job seeker onboarding, completion rates, trends
`adminSystemHealth`	Log level counts, errors last 24h/7d, errors by service, recent errors
`adminPromoCodeStatistics`	Active codes, total redemptions, total discount given
`adminAuditLogs`	Paginated audit logs with filters (action, entity type, date range)
`adminLookupUser`	Detailed user info by ID: companies, candidatures, subscription
`adminLookupCompany`	Detailed company info by ID: members, jobs, talent pools, candidates

Example: Dashboard Query

query AdminDashboard {
  overview: adminPlatformOverview {
    totalUsers
    totalCompanies
    totalJobs
    monthlyRecurringRevenue
    activeSubscriptions
  }
  users: adminUserStatistics {
    totalUsers
    usersCreatedThisWeek
    statusBreakdown { verified unverified }
  }
  revenue: adminRevenueStatistics {
    monthlyRecurringRevenue
    subscriptionsByStatus { ACTIVE TRIALING PAST_DUE }
  }
  health: adminSystemHealth {
    errorsLast24Hours
    warningsLast24Hours
  }
}

RBAC Management (14 Operations)

The platform has 8 roles in 3 tiers and 39 permissions across 13 feature modules. See Security & Authentication for the full role–permission matrix.

Current roles: Super Admin, Company Admin, Internal Sales, Recruiter/HR, External Sales, Economy, Auditor/Viewer, support.

Permission modules (13): Opportunities, CV Database, Task Board, Contact List, Statistics, Share CV List, Share Job List, Network Expansion, Grow Company, Subscriptions, Projects, Tracking System, Economy — each with READ, WRITE, DELETE levels.

Role CRUD

Operation	Type	Description
`adminListRoles`	Query	List roles with pagination and search
`adminGetRole`	Query	Role details with permissions and assignment count
`adminCreateRole`	Mutation	Create role with optional permission IDs
`adminUpdateRole`	Mutation	Update name, description, permissions (replaces existing)
`adminDeleteRole`	Mutation	Delete role (fails if active assignments exist)

Permission CRUD

Operation	Type	Description
`adminListPermissions`	Query	List all 39 module permissions with pagination and search
`adminCreatePermission`	Mutation	Create permission (name must be unique)
`adminUpdatePermission`	Mutation	Update permission name or description
`adminDeletePermission`	Mutation	Delete permission (fails if assigned to roles)

Role Assignments

Operation	Type	Description
`adminListRoleAssignments`	Query	List `UserCompanyRole` assignments filtered by user/company/role
`adminAssignRole`	Mutation	Assign role to user in a company (creates `UserCompanyRole`)
`adminRevokeRole`	Mutation	Revoke a role assignment by ID
`adminBulkAssignRole`	Mutation	Assign role to multiple users at once
`adminRbacStatistics`	Query	Role usage stats and assignment trends

Example: Create Role

mutation {
  adminCreateRole(input: {
    name: "Recruiter Lead"
    description: "Senior recruiter with full pipeline access"
    permissionIds: ["perm-uuid-1", "perm-uuid-2"]
  }) {
    success
    message
    role { id name }
  }
}

Super Admin Management (2 Operations)

Operation	Type	Description
`adminListSuperAdmins`	Query	List all users with SuperAdmin status (returns `AdminListSuperAdminsResult!`)
`adminSetSuperAdmin`	Mutation	Grant or revoke SuperAdmin status for a user (input: `AdminSetSuperAdminInput!`, returns `AdminSetSuperAdminResult!`)

warning

Cannot modify your own SuperAdmin status. The mutation prevents self-demotion for safety.

Example: Grant Super Admin

mutation {
  adminSetSuperAdmin(input: {
    userId: "user-uuid"
    isSuperAdmin: true
    reason: "Promoted to platform administrator"
  }) {
    success
    message
    userId
    isSuperAdmin
    email
  }
}

Example: List Super Admins

query {
  adminListSuperAdmins {
    superAdmins { id email firstName lastName }
    total
  }
}

User Management (2 Mutations)

Operation	Type	Description
`adminDeleteUser`	Mutation	Soft or hard delete a single user
`adminBulkDeleteUsers`	Mutation	Bulk delete up to 50 users

Safety Restrictions

Cannot delete your own account via admin mutations
Cannot delete users with isSuperAdmin: true
Hard delete requires confirmHardDelete: true
Bulk operations capped at 50 users per request

Example: Soft Delete

mutation {
  adminDeleteUser(input: {
    userId: "user-uuid"
    deleteType: SOFT
    reason: "User requested account closure"
  }) {
    success
    message
    deletedUserId
    deleteType
  }
}

Billing Administration (13 Operations)

Plan & Credit Pack Management

Operation	Type	Description
`createPlan`	Mutation	Create subscription plan
`updatePlan`	Mutation	Update plan details
`removePlan`	Mutation	Delete a plan
`createCreditPack`	Mutation	Create purchasable credit pack
`updateCreditPack`	Mutation	Update credit pack
`removeCreditPack`	Mutation	Delete credit pack

Subscription & Credit Admin

Operation	Type	Description
`adminAssignSubscription`	Mutation	Assign subscription to company without payment
`adminGrantCredits`	Mutation	Grant credits to company or user (max 1M per grant)
`creditCostConfigs`	Query	List all AI model credit cost configurations
`createCreditCostConfig`	Mutation	Set per-token pricing for an AI model
`updateCreditCostConfig`	Mutation	Update model credit costs
`deleteCreditCostConfig`	Mutation	Soft-delete config (sets `isActive: false`)
`adminAIOperationLogs`	Query	Platform-wide AI operation logs with filters

info

adminGrantCredits requires exactly one of companyId or userId -- not both. Company ID targets the employer balance; user ID targets the job seeker balance.

Additional Admin Sections

Company Management

Operation	Type	Description
`adminListCompanies`	Query	List companies with search, status filter
`adminGetCompany`	Query	Detailed company info with subscription and owner
`adminSuspendCompany`	Mutation	Suspend company and deactivate subscriptions
`adminReactivateCompany`	Mutation	Reactivate a suspended company
`adminTransferOwnership`	Mutation	Transfer company ownership to another user

Credit & Subscription Dashboard

Operation	Type	Description
`adminListCreditBalances`	Query	All credit balances with search
`adminGetCreditBalance`	Query	Balance details with recent transactions
`adminCreditStatistics`	Query	Platform credits in circulation, top consumers
`adminAdjustCredits`	Mutation	Manual credit adjustment (positive or negative)
`adminListSubscriptions`	Query	Subscriptions filtered by status/plan
`adminGetSubscription`	Query	Full subscription details including Stripe ID
`adminExtendSubscription`	Mutation	Extend subscription end date
`adminCancelSubscription`	Mutation	Cancel subscription (DB-level, not Stripe-synced)
`adminChangePlan`	Mutation	Change subscription plan

AI Operations Dashboard (Read-Only)

Operation	Type	Description
`adminAIOperationsOverview`	Query	Total operations, tokens, credits, 30-day trends
`adminAIOperationsByType`	Query	Breakdown by operation type (CV, matching, etc.)
`adminTopAIConsumers`	Query	Top companies/users by credit consumption
`adminAIOperationLogs`	Query	Paginated logs with type/status/date filters

Feature Flags

Operation	Type	Description
`adminListFeatureFlags`	Query	List all feature flags
`adminGetFeatureFlag`	Query	Get flag by key
`adminSetFeatureFlag`	Mutation	Create or update flag (upsert by key)
`adminDeleteFeatureFlag`	Mutation	Delete flag by key

Site Status (Public — No Auth)

Operation	Type	Description
`publicSiteStatus`	Query	Public, unauthenticated. Returns maintenance-mode status for the landing page, signin screen, and authenticated routes. Polled by frontend every 60s.

Returns:

type PublicSiteStatusOutput {
  landingLocked: Boolean!
  companiesLocked: Boolean!
  jobseekersLocked: Boolean!
  endsAt: String        # ISO 8601 or null
  serverNow: String!    # ISO 8601 — always fresh, never cached
  message: String
  reason: String
  supportContact: String
  statusPageUrl: String
}

Backed by 8 SystemSetting keys (same table as feature flags, written via adminSetFeatureFlag):

Key	Type	Notes
`maintenance_landing`	boolean	`"true"` / `"false"` string
`maintenance_companies`	boolean	`"true"` / `"false"` string
`maintenance_jobseekers`	boolean	`"true"` / `"false"` string
`maintenance_ends_at`	string	ISO 8601 or empty string (unset)
`maintenance_message`	string	Long message, shown on screen
`maintenance_reason`	string	Short reason, shown on screen
`maintenance_support_contact`	string	Email or URL, optional
`maintenance_status_page_url`	string	URL, optional

Server-side behavior:

Empty-string values coerced to null
If maintenance_ends_at parses to a valid date and is in the past, all three *Locked fields are forced to false regardless of stored values (authoritative expiry enforcement — stale caches can't trick the client)
endsAt is still returned verbatim so the frontend can display the original schedule
10s in-memory TTL cache on the flag projection (not serverNow — that's recomputed every call)
Cache is busted on admin.featureFlag.{created,updated,deleted} events for maintenance_* keys, so admin toggles propagate to anonymous pollers within one poll cycle

See the Maintenance Mode Runbook for operational steps.

Job Moderation & Email Management

Operation	Type	Description
`adminListJobs`	Query	Jobs with status/company/search filters
`adminGetJob`	Query	Detailed job with candidate/interview counts
`adminUpdateJobStatus`	Mutation	Moderate job status (NEW, IN_PROGRESS, CLOSED, DRAFT)
`adminListEmails`	Query	Email delivery logs with filters
`adminGetEmail`	Query	Full email content and delivery details
`adminEmailStatistics`	Query	Delivery rate, sent/failed/pending counts
`adminResendEmail`	Mutation	Resend a failed email

Schema Introspection

Operation	Type	Description
`databaseSchema`	Query	Full Prisma schema text from connected DB
`modelSchema`	Query	Schema for a specific model by name
`schemaComparison`	Query	Compare local vs database schema, diff report
`databaseEnums`	Query	All enum definitions

Monitoring

Operation	Type	Description
`applicationLogs`	Query	Recent logs filtered by level, service, correlation ID
`errorLogs`	Query	Recent error logs
`logStats`	Query	Log counts and error summary
`serviceLogStats`	Query	Per-service log and error counts
`logStream`	Subscription	Real-time log streaming via Redis pub/sub

Error Codes

Error	Code	Description
Unauthorized	401	Missing or invalid JWT token
Forbidden	403	User is not a superadmin
Not Found	404	Resource not found (lookup queries)
Bad Request	400	Validation failure (e.g., bulk delete exceeds 50)

Authentication​

Platform Analytics (15 Queries)​

Example: Dashboard Query​

RBAC Management (14 Operations)​

Role CRUD​

Permission CRUD​

Role Assignments​

Example: Create Role​

Super Admin Management (2 Operations)​

Example: Grant Super Admin​

Example: List Super Admins​

User Management (2 Mutations)​

Example: Soft Delete​

Billing Administration (13 Operations)​

Plan & Credit Pack Management​

Subscription & Credit Admin​

Additional Admin Sections​

Company Management​

Credit & Subscription Dashboard​

AI Operations Dashboard (Read-Only)​

Feature Flags​

Site Status (Public — No Auth)​

Job Moderation & Email Management​

Schema Introspection​

Monitoring​

Error Codes​