HMRC MTD API Authentication & Token Management
HMRC MTD API Authentication & Token Management
Available from: v1.0.4
This page explains how the platform authenticates with HMRC's Making Tax Digital (MTD) API on behalf of landlords, how access tokens are managed, and what landlords need to provide to get started.
Overview
To submit quarterly tax data to HMRC under Making Tax Digital, the platform must be authorised by HMRC to act on each landlord's behalf. This is done using the OAuth 2.0 authorisation code flow — the mechanism mandated by HMRC for all MTD-compatible software.
Once a landlord completes the one-time authorisation, the platform stores their access credentials securely and refreshes them automatically. Landlords do not need to re-authorise unless they explicitly revoke access.
Requirements
Before starting the authorisation flow, a landlord must have:
- A valid HMRC Government Gateway account with MTD for Income Tax enrolled.
- Their National Insurance Number (NINO) — this is captured during the authorisation handshake and is required by HMRC to uniquely identify the taxpayer.
The Authorisation Flow
The platform implements the standard OAuth 2.0 authorisation code flow against HMRC's MTD API endpoints:
- Initiate — The landlord clicks "Connect to HMRC" within their account. The platform redirects them to HMRC's Government Gateway login page.
- Authenticate with HMRC — The landlord signs in to their Government Gateway account and grants the platform permission to submit MTD data on their behalf.
- National Insurance Number capture — As part of the handshake, the landlord's National Insurance Number is collected and stored against their landlord record. This is mandatory for HMRC to process submissions.
- Token exchange — HMRC returns an authorisation code, which the platform exchanges for an access token and a refresh token.
- Confirmation — The landlord is returned to the platform. Their account is now connected to HMRC MTD.
Token Storage & Refresh
Per-Landlord Token Isolation
Access tokens and refresh tokens are stored per landlord. Each landlord's HMRC credentials are fully isolated — one landlord's token lifecycle has no effect on another's.
Automatic Token Refresh
HMRC access tokens are short-lived. The platform monitors token expiry and uses the stored refresh token to obtain a new access token automatically and transparently before the current one expires. This means:
- Submissions are never interrupted due to an expired token.
- Landlords are not prompted to re-authorise on a recurring basis.
- No manual intervention is required for routine token management.
Token Revocation
If a landlord revokes the platform's access via their HMRC Government Gateway account, the stored tokens will become invalid. The platform will detect this on the next submission attempt and prompt the landlord to re-authorise.
National Insurance Number
HMRC requires a valid National Insurance Number as part of the MTD identity verification process. The NINO:
- Is captured once during the initial OAuth authorisation handshake.
- Is stored securely against the landlord's record.
- Is included in all subsequent HMRC API calls that require taxpayer identification.
- Must be correct — HMRC will reject submissions where the NINO does not match the Government Gateway account.
Format: A valid UK NINO follows the pattern XX 99 99 99 X (e.g. QQ 12 34 56 C). The platform validates the format before submission.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
| "Not authorised with HMRC" error | OAuth flow not completed | Complete the "Connect to HMRC" authorisation flow |
| Submission rejected by HMRC | NINO mismatch or missing | Verify the National Insurance Number on file matches your Government Gateway account |
| "Token expired" or repeated auth prompts | Refresh token revoked or expired | Re-authorise via "Connect to HMRC" |
| Authorisation page not loading | HMRC service outage | Check HMRC API service availability |