Connecting to HMRC Making Tax Digital — OAuth2 Authentication
Connecting to HMRC Making Tax Digital — OAuth2 Authentication
Introduced in v1.0.7
Before any tax data can be submitted to HMRC, your account must be connected to HMRC's Making Tax Digital (MTD) API via the Government Gateway OAuth2 flow. This page explains what that means, what you'll need, and how it works.
What Is the OAuth2 Connection Flow?
HMRC's Making Tax Digital API uses OAuth2 (specifically the authorisation code grant) to confirm that you have given this platform permission to act on your behalf with HMRC. This means:
- You are redirected to the official HMRC Government Gateway login page.
- You sign in with your own Government Gateway credentials.
- HMRC asks you to confirm you consent to this platform submitting data on your behalf.
- You are redirected back to the platform, now authenticated.
No passwords are stored by this platform. Only the access token and refresh token issued by HMRC are retained, and these are stored securely.
What You'll Need
Before starting the connection process, make sure you have the following to hand:
| Requirement | Details |
|---|---|
| Government Gateway User ID | Your HMRC online services login username |
| Government Gateway Password | Your HMRC online services login password |
| National Insurance Number (NINO) | Required by HMRC as part of the MTD sign-on process |
| MTD Enrolment | Your HMRC account must already be enrolled for Making Tax Digital for Income Tax |
Note: If you are not yet enrolled for MTD for Income Tax, visit HMRC's MTD sign-up service before proceeding.
How the Connection Works
Step 1 — Initiate the Connection
From your account settings, navigate to HMRC Connection and click Connect to HMRC. The platform will redirect you to the HMRC Government Gateway.
Step 2 — Sign In to Government Gateway
Enter your Government Gateway User ID and password on the HMRC-hosted page. The platform never sees these credentials.
Step 3 — Grant Consent
HMRC will present a consent screen listing the permissions being requested (e.g. submit income tax updates). Review and confirm.
Step 4 — Return to the Platform
After granting consent, you are automatically redirected back. The platform securely stores the issued tokens and your connection status will show as Connected.
Token Management
Once connected, the platform manages your HMRC session automatically:
- Access tokens are short-lived (typically 4 hours) and are used to authorise each API call to HMRC.
- Refresh tokens are longer-lived and are used to silently obtain a new access token when the current one expires — no action is required from you.
- Tokens are stored encrypted and are never returned to the browser or logged.
Why This Step Is Required
This OAuth2 connection is the foundational integration for all Making Tax Digital functionality. Without a valid authenticated connection:
- Quarterly updates cannot be submitted to HMRC.
- Property income and expense data cannot be reported.
- Final declarations cannot be made.
All subsequent MTD features depend on a successfully established connection.
Troubleshooting
I was redirected back but my status still shows "Not Connected" This can happen if the authorisation was denied or timed out. Try initiating the connection again and ensure you click Allow on the HMRC consent screen.
My Government Gateway account isn't recognised Ensure you are using the correct credentials for the account that holds your MTD for Income Tax enrolment. Personal and business Government Gateway accounts are separate.
The connection expired and submissions are failing The platform refreshes tokens automatically. If a refresh fails (e.g. you revoked access via HMRC's portal), you will need to re-connect by repeating the OAuth2 flow from account settings.