All Docs
FeaturesMaking Tax DigitalUpdated February 19, 2026

HMRC MTD OAuth2 Authentication Flow

HMRC MTD OAuth2 Authentication Flow

This page documents how the platform connects landlords to HMRC's Making Tax Digital (MTD) service using the OAuth2 authorisation flow.

Overview

To submit quarterly tax updates to HMRC under Making Tax Digital for Income Tax Self Assessment (MTD ITSA), the platform must act on behalf of the landlord when communicating with HMRC's APIs. This is achieved through the industry-standard OAuth2 Authorisation Code flow, as mandated by HMRC.

Once connected, the platform can securely read and submit Income Tax data to HMRC using the MTD Individual Income Tax API, scoped to each individual landlord's account.

How It Works

1. Initiating the Connection

The landlord starts the connection process from within the app. They are redirected to HMRC's authorisation server, where they log in with their HMRC Government Gateway credentials and grant the app permission to act on their behalf.

2. Authorisation Code Exchange

After the landlord grants consent, HMRC redirects back to the app with a short-lived authorisation code. The platform exchanges this code for:

  • An access token — used to authenticate API calls to HMRC on the landlord's behalf.
  • A refresh token — used to obtain new access tokens when the current one expires.

3. Secure Per-User Token Storage

Tokens are stored per user — each landlord's HMRC credentials are fully isolated from other users. Access tokens and refresh tokens are stored securely and are never exposed client-side.

4. Automatic Token Refresh

HMRC access tokens are short-lived. The platform automatically refreshes them in the background using the stored refresh token before they expire. Landlords do not need to re-authorise frequently.

OAuth2 Scope

The authorisation request is scoped specifically to:

read:self-assessment write:self-assessment

This corresponds to the MTD Individual Income Tax API, limiting the platform's access to only what is required for Making Tax Digital compliance. No other HMRC services are accessed.

HMRC Requirements

HMRC's Making Tax Digital programme requires:

  • Use of the official OAuth2 authorisation code flow (not client credentials or other grant types).
  • Submission of the landlord's National Insurance Number (NINO) when interacting with MTD APIs.
  • Token-based authentication on every API call to HMRC.

The platform handles all of the above on the landlord's behalf once the initial authorisation is complete.

Connecting Your HMRC Account

  1. Log in to the platform.
  2. Navigate to Settings → HMRC Connection.
  3. Click Connect to HMRC.
  4. You will be redirected to HMRC's Government Gateway sign-in page.
  5. Sign in with your Government Gateway credentials.
  6. Review and Approve the permissions requested by the app.
  7. You will be redirected back to the platform — your HMRC account is now connected.

Once connected, the platform will use your HMRC authorisation to submit quarterly updates on your behalf.

Disconnecting Your HMRC Account

You can revoke the platform's access to your HMRC account at any time:

Revoking access will prevent any further submissions to HMRC until you reconnect.

Security Notes

  • Tokens are stored server-side and are never accessible from the browser.
  • Each landlord's tokens are scoped to their individual account — no shared credentials.
  • The platform only requests the minimum OAuth2 scopes required for MTD Income Tax submissions.
  • Token refresh is handled automatically and securely without any user interaction required.