All Docs
FeaturesMaking Tax DigitalUpdated February 20, 2026

Blog: Connecting to HMRC Making Tax Digital — How OAuth2 Authentication Works in v1.0.7

Connecting to HMRC: How the OAuth2 Authentication Flow Works in v1.0.7

Release: v1.0.7 — HMRC MTD OAuth2 Connection Flow

Every Making Tax Digital submission to HMRC requires a verified, authorised connection. With v1.0.7, that foundational link is now in place.

The Problem This Solves

HMRC's Making Tax Digital for Income Tax requires landlords to submit quarterly updates and final declarations digitally. To do this on a landlord's behalf, any software must first prove — to HMRC's satisfaction — that the landlord has explicitly granted it permission. Without that proof, every API call is rejected.

The mechanism HMRC uses for this is OAuth2 via Government Gateway. Until this release, the platform had no way to establish or maintain that permission. v1.0.7 changes that.

What Was Built

Government Gateway OAuth2 Flow

The platform now supports the full OAuth2 authorisation code grant flow as required by HMRC. When a landlord initiates the connection:

  1. They are redirected to HMRC's own Government Gateway login — the same interface they use for Self Assessment, VAT, and other HMRC services.
  2. After signing in, HMRC presents a consent screen. The landlord reviews and approves the permissions.
  3. HMRC issues an authorisation code, which the platform exchanges for an access token and a refresh token.

At no point does the platform handle or store Government Gateway passwords. Only the tokens issued by HMRC are retained.

Secure Token Storage

The access token and refresh token returned by HMRC are stored securely. These credentials are what allow the platform to make authenticated requests to the MTD API — for example, to submit a quarterly income update or retrieve obligation periods.

Automatic Token Refresh

HMRC access tokens are short-lived. Rather than requiring landlords to re-authenticate every few hours, the platform uses the stored refresh token to obtain a new access token silently and automatically. The landlord's connection stays live without any manual intervention.

Why This Release Matters

This is explicitly a foundational release. The OAuth2 connection is not a feature in isolation — it is the prerequisite for everything else:

  • Without it, quarterly updates cannot be submitted.
  • Without it, obligation periods cannot be retrieved from HMRC.
  • Without it, final declarations cannot be filed.

Every MTD feature that follows — quarterly submissions, income and expense categorisation, AgentOS transaction import — depends on the connection established in this release.

What Landlords Need

To connect their account, landlords will need:

  • A Government Gateway User ID and password for the account enrolled in MTD for Income Tax.
  • Their National Insurance Number (NINO), which HMRC requires as part of the MTD sign-on.
  • An active MTD for Income Tax enrolment on their Government Gateway account.

If a landlord is not yet signed up for MTD for Income Tax, they will need to complete HMRC's sign-up process before connecting.

What's Next

With authentication in place, subsequent releases will build directly on this foundation — starting with retrieving HMRC obligation periods and submitting quarterly income and expense updates. The AgentOS transaction import, which pulls landlord property financials directly into the platform, will feed data into those submissions.

Released as part of the UK Landlord MTD platform. For setup instructions, see the HMRC Connection guide.