How an accountant runs a client's tax cycle in AccountantUK

The five-step loop from connecting your Agent Services Account to a SHA-256 hashed, immutable receipt in the audit log. Below the narrative there's an honest breakdown of which returns are wired for direct submission — held closed until our HMRC production access lands — and which we hand back as a ready-to-upload artefact.

1. Step 1 — One-time setup

   The HMRC handshake

   Inside the accountant portal, click Connect to HMRC. We run the UK Government OAuth flow against your firm's master Agent Services Account (ASA) credentials. The returned authorisation token is encrypted at rest with AES-256-GCM (see lib/secrets.ts) before it ever touches the database. From that point on the software has legal API access to file for any client that has authorised your firm — no client passwords, no shared Gateway logins.

2. Step 2 — Doing the work

   Act as the client

   From your master client list, find the client and click Act-As. We set a server-signed cookie (ACT_AS_MAX_AGE_SEC = 4 hours) and your screen becomes the client's dashboard. Review the AI-scanned receipts, check the ledgers, let the tax module compute the figures. You never see the client's password and never need a 2FA code. Every page load you make in act-as mode is recorded in the audit log against your real identity.

3. Step 3 — Legal sign-off

   Send for client approval

   UK law: you can't push the final Submit button without explicit written approval from the client. Click Send for Approval and the figures land in the Quarterly Reviews module (status DRAFT). The client gets an alert on their phone, opens the app, reviews the math, taps Approve. The record transitions to APPROVED, audit-logged with the client's identity and timestamp. Days of email chase replaced by a tap.

4. Step 4 — The submission

   The submission payload

   Once the review is APPROVED, the backend compiles the MTD REST payload or GovTalk XML envelope for the module (VAT, ITSA quarterly, ITSA crystallise, RTI FPS, CIS300) and attaches the HMRC fraud-prevention headers (Gov-Client-* device + IP + timezone, computed by lib/hmrc-fraud-headers.ts). Transmission to HMRC is switched off today — a fail-closed guard (lib/hmrc-filing-guard.ts) blocks every submit path until our HMRC production credentials land, and the UI disables the button rather than pretending otherwise. What you get right now is the exact payload, ready to review and export. The remaining modules (CT600, SA800, CGT, SDLT, P11D) stop one step earlier by design — we generate the iXBRL or computation file for you to upload to the relevant HMRC / Companies House portal yourself.

   Wired for direct filing: VAT · ITSA · RTI FPS · CIS300Compute & export — you file: CT600 · SA800 · CGT · SDLT · P11D

5. Step 5 — Forensic defensibility

   Immutable receipt + audit log

   When transmission is live, HMRC replies with a Correlation ID. We render the receipt PDF (e.g. lib/vat-receipt-pdf.ts for VAT), hash it with SHA-256, and write the bytes + hash to private Vercel Blob storage. The action is appended to the audit log (lib/audit.ts — append-only by design). If HMRC ever investigates the client years later, the accountant has forensic proof of exactly what was filed, when, by whom, and that the client signed off first.