Operating HireQ as a super admin.

Audience: HireQ platform operators (super admins)
Portal: after you sign in you land on /dashboard
Last updated: 2026-10-01 (beta)
Online: www.hireq.ca/guides/admin.html · Version française

This guide describes the admin workspace as built in the unified portal (portal/). Server setup and go-live steps are in ops/beta-go-live-checklist.md and env.md. SMTP, logos, and the Emails editor: email-setup.md.

Beta notice. The platform runs with Stripe in test mode (PAYMENTS_MODE=sandbox). Services need test-mode Stripe Price IDs, and users pay with test cards. Do not enter live Price IDs during the beta. Live cutover later: ops/stripe-live-cutover.md.

Related role guides: Quick Guide · Candidate guide · Recruiter guide
Deeper schema design: validation-user-guide.md
How schema, taxonomy, skills, and matching scores fit together: §3

1. How you get in

1.1 Creating an admin account

Admins cannot register on /register, and there is no admin env variable. Someone with shell access to the API server runs:

cd /opt/hireq/backend
.venv/bin/python scripts/create_admin_user.py --email you@hireq.ca

The script prompts for the password twice. The password must be at least 10 characters, not only numbers, and not the email address. Running it again for an existing admin resets that admin's password (and reactivates the account). It refuses to turn an existing candidate/recruiter email into an admin.

1.2 Signing in

• Sign in on the same login page as everyone else (/). You are routed to /dashboard.
• If 2FA is on, enter the Authenticator code when asked.
• Deep links: /dashboard?section=matching, validation-schema, taxonomy, emails, audit, skills, account, and so on.
• The admin UI is English only.
• If the session is invalid, you are sent back to /.

1.3 Account security (password and 2FA)

Sidebar → Account security.

• Change password — current password + new password (same rules as above).
• Authenticator app (2FA) — Set up 2FA → add the key to your authenticator app → enter the 6-digit code → Turn on 2FA. To turn it off you need your password and a current code.

2FA is optional in the software, but beta policy is that every admin turns it on. Admins can see all candidate data, recordings, and payments.

1.4 Lost 2FA device (support procedure)

There are no self-service recovery codes yet. For any user (admin, recruiter, or candidate) who lost their authenticator:

1. Verify identity out of band (known email + a second channel you trust).
2. An operator with database access clears 2FA for that user: set totp_enabled = false and totp_secret = NULL on the users row.
3. Ask the user to sign in with their password and set up 2FA again.
4. Note the reset in your support log.

2. What you operate

HireQ is not a “flip a feature flag” admin. You operate the rulebooks and catalogs that candidates and recruiters live inside:

AI never auto-hires or auto-rejects. Your Matching toggles can notify and present opportunities; candidates still consent. Recruiters still move pipeline status by hand.

3. Validation Schema, Job Taxonomy, skills, and matching scores

These admin surfaces look separate in the sidebar, but they form one pipeline. Candidates and recruiters never edit them; they live inside the rules and occupation data you activate.

3.1 Validation Schema (the rulebooks)

There are two live schemas (each versioned; only the active version applies):

A schema is not a list of occupations or skill names. It is structural (“skills must exist,” “ask about {keyword},” “publish needs readiness ≥ X”). The same candidate schema works for any skill the candidate adds.

Default candidate settings (bundled / typical active): readiness weights self-declared 0.15 / manual 0.35 / AI 0.5; completeness_divisor 11; validated_score_threshold 0.7; low_ai_gap_threshold 0.5. Completion checks include full name, location, phone, summary, target roles, work preferences, work history, skills, languages, education, certifications (several allow “none” via assistant decline).

Default job settings: self-declared weight 1.0; publish_readiness_threshold 0.6; recommendation_readiness_threshold 0.6; min_required_skills 1; required_locales ["en"]. Completion: English title & description, ≥1 skill, location (city or location), employment type, work model.

If no DB version is active, the API falls back to bundled JSON under backend/config/.

3.2 Job Taxonomy (the occupation tree)

Taxonomy is content: categories → families → canonical job titles → family skills.

Import needs two files (CSV UTF-8 or .xlsx):

Skills / competencies file columns:
Category ID, Category, Job Family ID, Job Family, Skill ID, Skill, Skill Type, Importance, Expected Proficiency, Validation Method, Interview Weight, Question Required

Canonical titles file columns:
Category ID, Category, Job Family ID, Job Family, Job ID, Job Title

Notes that matter in production:

• Taxonomy Skill ID is an external id on the taxonomy row. Matching keys off the platform Skill.id created/upserted by skill name (case-insensitive). Duplicate dictionary keywords still break matching.
• Import requires a version label. Same file checksum returns the existing version (may activate it).
• Activate makes that version the only active one (effective_at set).

When a recruiter Builds family baseline, family skills become proposed JobRequirement rows:

Without taxonomy coverage for a role, recruiters can still draft a job with freeform posting skills, but the evidence-matching path needs a canonical title + confirmed requirements.

3.3 Skills catalog vs candidate skills vs taxonomy skills

Candidate skills are not limited to the taxonomy. Free-text skills can create new catalog entries. Skill validation (candidate UI) generates questions if the bank is empty (see §6).

3.4 How matching scores are produced (code behavior)

Evidence matching (assess_match) compares confirmed job requirements for the job’s current specification version against the candidate’s skill claims (approved skill equivalencies can map related skills).

Admin activates taxonomy + candidate/job schemas + Matching settings
        ↓
Candidate adds skills → claims → Profile assistant / skill validation strengthens scores & levels
        ↓
Recruiter picks canonical title → Build family baseline → Confirm requirements → publish
        ↓
Job is matchable only if: published + assessment_ready + ≥1 confirmed requirement
        ↓
Per requirement: fit = claim_score × min(1, level / target_proficiency)
        ↓
fit_score = weighted average of fit
evidence_confidence = weighted average of evidence strength
suitability = fit_score × (0.5 + 0.5 × evidence_confidence)
        ↓
Recommendation label (hardcoded thresholds) + Matching settings for “strong” notify/auto-present

Per-requirement status:

• supported if fit ≥ 0.7 and evidence ≥ 0.5
• missing_evidence if evidence < 0.4 (or no claim)
• else partial

Hard gates: if a requirement has hard_gate and fit < 0.5, the candidate is ineligible and recommendation is needs_review.

Recommendation string (not the Matching settings thresholds):

Strong match (Matching settings — used for notify / auto-present):

• eligibility is not ineligible, and
• suitability ≥ suitability_threshold (default 0.7), and
• evidence_confidence ≥ evidence_threshold (default 0.5)

Matchable job requires all of: status == published, assessment_ready == true, and ≥1 confirmed requirement. assessment_ready becomes true when specification issues are cleared after confirms.

Publish (recruiter) is a second gate on top of specification: job schema completion must pass and job readiness ≥ publish_readiness_threshold (default 0.6).

Empty match reports usually mean missing taxonomy confirms, unpublished jobs, thin candidate skill evidence, or (on large datasets) the rematch candidate cap — not only “wrong thresholds.”

3.5 What you usually change vs leave alone

4. Sidebar map

Stats (candidates, recruiters, jobs, applications, scheduled vs performed interviews) stay visible while you switch sections.

5. Suggested go-live order (empty environment)

Do this before you ask a customer to UAT matching.

1. Lookups — load categories recruiters and candidates need (job type, work model, pay type, province, language fluency, education level, benefits, …).
2. Skills — seed the dictionary (taxonomy import also upserts skill names). Avoid duplicate keywords.
3. Job Taxonomy — download CSV templates, fill both files, Validate, Import (label required; activate-on-import defaults on), confirm an active version.
4. Validation Schema — activate a candidate schema and a job schema (import known-good JSON if needed).
5. Matching — review thresholds. Product defaults turn automation, notify, and auto-present ON. For conservative UAT, turn auto-present off until comfortable.
6. Emails — confirm SMTP and reset URLs (email-setup.md), upload the platform logo, preview Account setup / Password reset, then skim hiring templates recruiters will inherit.
7. Services — create Candidate Search (service id must match RECRUITER_CANDIDATE_SEARCH_SERVICE_ID, default 2) and any monthly recruiter plan with a Stripe Price ID. During the beta, use Price IDs from Stripe test mode.
8. Validation → LLM status / test — confirm the model endpoint answers before live candidate chat, and check the reported AI caps.
9. Account security — turn on 2FA for every admin.
10. Smoke: recruiter picks canonical title → baseline → confirm → publish; candidate completes Profile assistant (+ skill validation); Matching report is non-empty. Register a spare inbox and confirm the password-setup email arrives. Buy Candidate Search with test card 4242 4242 4242 4242.

Export/import scripts for skills, lookups, and services also exist under backend/scripts/ for environment copies.

6. Lookups and skills

Lookups are (category, code, item) rows. Category+code must be unique. After Add, the form keeps the category so you can enter many codes quickly. Filter by category when the list is long. Unknown categories that already exist in data are listed as orphans so you can clean them.

Skills is a flat keyword list used by candidate pickers, recruiter job skills, taxonomy name upsert, and matching. Add carefully — duplicates confuse matching (§3.3).

Validation questions (per skill):

• Max 10 active questions (skill.question_bank_full if exceeded).
• If the bank is empty, skill validation generates toward a target bank of 5; a session uses up to 5 questions.
• Prompt minimum length 12 characters. Deactivate / reactivate in the UI; no delete control.

7. Job Taxonomy

Operational steps (concepts in §3.2):

1. Download the skills and jobs CSV templates (columns and examples are on screen).
2. Validate uploads without activating.
3. Import with a required label; optionally activate on import (default checked in UI).
4. Open a version to see counts (categories, families, titles, skills).
5. Activate the version recruiters should use.

Recruiters pick canonical titles from the active version. Family baseline in Hiring tools depends on this. Legacy free-text titles can be backfilled with backend/scripts/backfill_legacy_job_titles.py if operations needs it.

8. Validation Schema

There are two schemas: candidate and job. Each is versioned. Activating a version makes it the live rulebook; old versions remain for history.

Editor modes: Structured and JSON. Structured tabs cover:

• Settings (weights, thresholds; job schema also has publish/recommendation thresholds, min skills, locales)
• Categories
• Materializers
• Completion requirements
• Gap prompts
• Portal groups

Actions: Validate → Save new version → Save & activate → Export active; history Load / Activate; JSON Apply / Import as version (import alone does not activate).

Candidates never see this screen; they see Profile assistant. Recruiters see Job quality gaps driven by the job schema.

Make small, reviewed changes. A broken completion rule blocks publishing or looks like a candidate “cannot finish” their profile.

9. Validation (human review)

Queue lists candidates with validation activity.

Open a candidate to see claims, scores, statuses, and a timeline of decisions. You can:

• Patch score/status
• Override with a reason (audited write path). For skill claims, the override also sets the stored 1–10 proficiency used in matching
• Attach evidence notes
• Open interview review when assessments exist

Trust labels (for example “Strong evidence”) are derived from readiness, not a separate product.

LLM status and Test connection tell you whether the validation model is reachable. Use this when Profile assistant hangs or returns errors.

LLM status also shows the spend caps: max_output_tokens, daily_call_limit (platform-wide), and daily_call_limit_per_user. When a cap is reached, AI calls stop until midnight UTC and the product falls back to simpler, non-AI behaviour (for example, built-in profile questions instead of AI follow-ups). If users report "generic" assistant replies late in the day, check the API logs for LLM platform daily cap reached and ask ops to raise LLM_DAILY_CALL_LIMIT if the budget allows.

Interview review and recordings

Open a candidate (Validation queue or Candidates) to reach the Interviews list. Each session shows the recording player (audio/video sessions) and every question and answer. Admins can review any session.

• Recordings live in a private bucket and play through short-lived links.
• They are deleted automatically 180 days after the assessment ends by the retention job (hireq-recording-retention.timer). Each deletion writes a recording.purged audit event. Transcripts and scores stay.
• If a candidate asks for an earlier deletion, or a legal hold requires keeping one longer, escalate to ops — there is no per-recording delete button.

10. Matching

This section is policy on top of scores (when to rematch, notify, or auto-present). Score math lives in §3.4. Recommendation labels use hardcoded cutoffs; these settings define strong match for automation.

Recruiters can still click Present opportunity on a match when auto-present is off.

Matching only considers matchable jobs (§3.4). If reports are empty, check taxonomy, confirms, publish, assessment_ready, and candidate validation progress before changing thresholds.

11. Emails

Emails (/dashboard?section=emails) is the system default for every outbound HireQ message. Recruiters can override hiring types for their company; they cannot change auth, billing, sender address, or the HireQ logo.

Full SMTP + editor walkthrough, catalog, and merge fields: email-setup.md.

On this screen you:

• Upload the platform logo (image, max 5 MB) used in email headers
• Edit subject, heading, body, and button label per message type
• Insert allowed merge-field chips (unknown {{tokens}} are rejected on save)
• Preview email with sample data, Save template, or Reset to default (built-in seed)

Notify on strong matches (Admin → Matching) still gates match emails. Turning notify off does not disable account-setup or interview calendar (ICS) mail.

12. Paid services

Create rows with:

• Audience — candidate or recruiter
• Billing — one_time or monthly
• Name, description, price, currency (default CAD)
• For recruiter + monthly: Stripe Price ID is required (Product ID optional)

Candidate monthly services are rejected by the API/UI. Recruiter Candidate Search must exist as a service whose id matches backend RECRUITER_CANDIDATE_SEARCH_SERVICE_ID (default 2) or recruiters cannot open Candidates.

Beta (test mode): create the matching Products/Prices in the Stripe Dashboard with Test mode switched on and paste those price_… IDs. Test-mode Price IDs do not work after live cutover; you will replace them as part of ops/stripe-live-cutover.md.

Deleting a service does not automatically refund Stripe customers.

13. Moderation and analytics

Candidates / Recruiters — search by email/name (company for recruiters). Deactivate blocks login; Reactivate restores. Deleted/inactive users cannot authenticate.

Jobs — search; set status draft, published, or closed. View counts help you see demand. Closing a job is a human moderation action; it is not an AI action. Admin status changes do not replace recruiter specification/quality gates for a healthy matching path.

Applications — search and filter by status; Inspect for interviews and candidate identity. You are not moving pipeline here (recruiters do).

Analytics — 30-day cards for signups, jobs posted, applications, revenue, job views. Export candidates, recruiters, or jobs as CSV.

14. Audit log

Read-only list of recent events: actor, role, action, resource, time. Typical actions include claim override, presenting a match, consent, application status, offers, a user turning 2FA off (auth.totp_disable), and automatic recording deletion (recording.purged).

14a. Terms, Privacy, and policy versions

• Registration requires accepting the current Terms and Privacy Policy. HireQ stores the accepted versions, time, and IP.
• Current versions: 2026-10-01 (PRIVACY_POLICY_VERSION, TERMS_VERSION). The published pages are drafts pending legal review.
• When ops bumps a version (after editing website/privacy.html / terms.html), every signed-in user sees a blocking We updated our Terms and Privacy Policy dialog and must accept before continuing. Bump only for material changes, and update the pages and env together.
• Users who refuse can ask support to delete their account (candidates can do it themselves in Settings → Privacy).

The screen does not yet expose filters or the JSON payload. If you need a specific action, engineering can query audit_events or call GET /admin/audit?action=….

15. What you should not expect from this workspace

• Editing a candidate’s profile as if you were them
• Recruiter-style pipeline moves
• French admin copy
• A status page or support-ticket product
• Starting Stripe refunds from the UI
• Live-joining a candidate’s AI video room
• Resetting another user's 2FA from the UI (use the §1.4 procedure)
• Creating admins from the UI (use create_admin_user.py)
• Deleting a single recording on demand (retention job only)
• Live Stripe payments during the beta
• Changing the SMTP From address in the Emails editor (that is EMAIL_FROM in env)
• A visual HTML drag-and-drop email builder

16. If something fails