Making Tax Digital (MTD) for Income Tax went live on 6 April 2026, and it's already mandatory for self-employed people and landlords whose qualifying income is over £50,000. That threshold drops to £30,000 in April 2027 and to £20,000 in April 2028, so the population it covers roughly triples over the next two years.

In practice, that means a lot of small businesses now need software that can send their figures to HMRC, and someone has to build that software.

The first time you open HMRC's developer documentation, it's a wall of acronyms: MTD, ITSA, OAuth scopes, fraud prevention headers, and obligations. It looks intimidating, and a lot of it is genuinely fiddly. But the path from zero to your first authenticated API call is more approachable than it looks once someone walks you through it in order.

That's what this guide does. I built the HMRC integration for a Making Tax Digital app, and I'm going to take you through the same steps I took, in the order I took them: what MTD is, how to get a sandbox app, how the OAuth login flow works, what those fraud prevention headers are, and how to make a real call. The code is Node and TypeScript, but the ideas carry over to any language.

Table of Contents

• What Making Tax Digital Actually is

• Step 1: Create a Sandbox Application

• Step 2: Understand the OAuth Scopes

• Step 3: The OAuth 2.0 Authorization Code Flow

• Step 4: Fraud Prevention Headers (the Part Nobody Warns You About)

• Step 5: Make Your First Authenticated Call

• Common Gotchas that Will Cost You an Afternoon

• Where to Go Next

What Making Tax Digital Actually is

Making Tax Digital is HMRC's programme to move tax record-keeping and filing into software.

Instead of one big annual Self Assessment return typed into a website, MTD for Income Tax asks people to keep digital records and send HMRC a cumulative update of their income and expenses every quarter, then a final declaration at the end of the year.

(For the official scope and timeline, see GOV.UK's MTD for Income Tax guidance.)

For developers, the important part is that HMRC doesn't give you a single "file my taxes" button. It gives you a set of REST APIs on its Developer Hub: one to list a person's businesses, one to read their filing obligations (what's due and when), one to submit the quarterly figures, one to trigger a tax calculation, and so on.

You compose these into a journey. Every one of them sits behind the same two gates: an OAuth 2.0 access token, and a set of fraud prevention headers. Get those two things right and the rest is ordinary JSON over HTTPS.

Step 1: Create a Sandbox Application

You never start against live taxpayer data. HMRC runs a full sandbox at test-api.service.hmrc.gov.uk that mirrors the production host (api.service.hmrc.gov.uk) and lets you create fake taxpayers to test with.

Here is the practical sequence:

1. Register for a free account on the HMRC Developer Hub.

2. Create an application. You get a client ID and a client secret. Treat the secret like a password: keep it in an environment variable, never in your source.

3. Set a redirect URI. This is the URL HMRC sends the user back to after they log in. For local work something like http://localhost:3000/auth/hmrc/callback is fine. It has to match exactly later, character for character.

4. Subscribe your application to the APIs you need. This is the step beginners miss. Listing it isn't enough. You click into each API and subscribe. If you forget, calls come back 403 Forbidden with no obvious reason.

In the code, the only thing that differs between sandbox and production is the base URL, so it's worth keeping those in config rather than hard-coding them:

const config = {
  sandbox: {
    baseUrl: 'https://test-api.service.hmrc.gov.uk',
    authUrl: 'https://test-api.service.hmrc.gov.uk/oauth/authorize',
    tokenUrl: 'https://test-api.service.hmrc.gov.uk/oauth/token',
  },
  production: {
    baseUrl: 'https://api.service.hmrc.gov.uk',
    authUrl: 'https://api.service.hmrc.gov.uk/oauth/authorize',
    tokenUrl: 'https://api.service.hmrc.gov.uk/oauth/token',
  },
};

One thing I learned the hard way: pick the environment from an explicit setting, not from NODE_ENV. You'll eventually want a production deployment that still points at the HMRC sandbox during a beta, and if your URLs are keyed off NODE_ENV alone, that combination forces production HMRC and rejects your sandbox credentials with client_id is invalid. A small HMRC_BASE_URL environment variable that always wins saves you that confusion.

Step 2: Understand the OAuth Scopes

When your app asks a user for access, it asks for specific scopes, which are named permissions. For MTD Income Tax the ones you want are read:self-assessment and write:self-assessment (HMRC also exposes read:vat and write:vat for the VAT APIs). HMRC documents these in its OAuth 2.0 authorisation guide. You join them with spaces:

const scopes = ['read:self-assessment', 'write:self-assessment'].join(' ');

The user sees these spelled out on HMRC's consent screen, so only ask for what you actually use.

Step 3: The OAuth 2.0 Authorization Code Flow

This is the heart of the integration, and it's the standard three-legged OAuth dance. Think of it as your app, the user, and HMRC passing a baton. There are four moments: send the user to HMRC, HMRC sends them back with a code, you swap the code for tokens, and later you refresh those tokens.

3a. Send the User to HMRC

You build an authorization URL and redirect the browser to it. The query string carries your client ID, the scopes, your redirect URI, response_type=code, and a state value:

function getAuthorizationUrl(state: string): string {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: hmrcConfig.clientId,
    scope: hmrcConfig.scopes,
    state: state,
    redirect_uri: hmrcConfig.redirectUri,
  });
  return hmrcConfig.authUrl + '?' + params.toString();
}

That state value matters. It's your defense against cross-site request forgery (CSRF). You generate a random, unguessable string, store it server-side, attach it here, and check it again when the user comes back. If the value that returns doesn't match one you issued, you reject the callback. A common pattern is to generate a UUID and stash it with the user's ID and a timestamp:

const state = uuidv4();
await setStateToken(state, { createdAt: Date.now(), userId });
res.redirect(getAuthorizationUrl(state));

The user now logs in on HMRC's own pages (with their Government Gateway credentials) and approves the scopes. Your app never sees their password, which is the whole point of OAuth.

3b. Handle the Callback

HMRC redirects back to your redirect URI with two query parameters: code and state (or an error if the user declined). First validate the state, then make it single-use by deleting it immediately so it can never be replayed:

const stored = await getStateToken(state);
if (!state || !stored) {
  return redirectError('Invalid or expired authorization request');
}
await deleteStateToken(state); // single-use: delete the moment it validates

// Optional but sensible: expire stale requests (here, 10 minutes).
if (Date.now() - stored.createdAt > 10 * 60 * 1000) {
  return redirectError('Authorization request has expired. Please try again.');
}

3c. Exchange the Code for Tokens

The code is short-lived and useless on its own. You exchange it, server to server, for an access token and a refresh token. This is a POST to the token endpoint with grant_type=authorization_code, form-encoded, including your client secret. The secret is why this happens on your backend and never in the browser:

async function exchangeCodeForTokens(code: string) {
  const response = await axios.post(
    hmrcConfig.tokenUrl,
    new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      client_id: hmrcConfig.clientId,
      client_secret: hmrcConfig.clientSecret,
      redirect_uri: hmrcConfig.redirectUri,
    }).toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
  );

  return {
    accessToken: response.data.access_token,
    refreshToken: response.data.refresh_token,
    expiresIn: response.data.expires_in, // seconds until the access token dies
  };
}

Store these tokens server-side, tied to the user, and never send them to the client. The access token is what authorises every later API call. Note expires_in: HMRC access tokens are short-lived (currently four hours), so you'll need step 3d.

3d. Refresh the Token

When the access token expires, you don't make the user log in again. You use the refresh token to get a fresh pair, with grant_type=refresh_token:

async function refreshAccessToken(refreshToken: string) {
  const response = await axios.post(
    hmrcConfig.tokenUrl,
    new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: hmrcConfig.clientId,
      client_secret: hmrcConfig.clientSecret,
    }).toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
  );
  return {
    accessToken: response.data.access_token,
    refreshToken: response.data.refresh_token,
    expiresIn: response.data.expires_in,
  };
}

A good habit is to check the stored token's expiry before each call and refresh proactively if it's close to running out. HMRC's OAuth documentation has the full lifecycle.

Step 4: Fraud Prevention Headers (the Part Nobody Warns You About)

Here's the surprise. Most APIs are happy with a bearer token. HMRC is not. By law, it requires your software to send a set of fraud prevention headers on every MTD call: a couple of dozen Gov-Client-* and Gov-Vendor-* headers describing the device, the network path, and the software making the request. They help HMRC detect credential abuse across thousands of third-party vendors.

This guide is about getting connected, so I'll keep this high level: read HMRC's Fraud Prevention Headers specification carefully, because the rules are precise and the failure modes are quiet.

The single most important decision is the connection method, sent in Gov-Client-Connection-Method. A server-mediated web app uses WEB_APP_VIA_SERVER; a server-mediated mobile app uses MOBILE_APP_VIA_SERVER. That choice decides which other headers are required and which are forbidden, so don't just emit everything.

The genuinely good news for beginners is that HMRC gives you a Test Fraud Prevention Headers API that inspects your request and tells you exactly which headers are missing or malformed. Build against that validator from your first commit and you turn a guessing game into a checklist.

You don't need the full depth of that spec to get your first sandbox call working, but you will need it before you go anywhere near production data, so budget real time for it rather than leaving it to the end.

Step 5: Make Your First Authenticated Call

Now you have a token and your headers. Time for a real request. Every MTD call sets two things on top of the token: an Accept header that pins the API version, and the fraud headers:

async function request(method, path, accessToken, req, data = null, apiVersion = '2.0') {
  const headers = {
    Authorization: `Bearer ${accessToken}`,
    Accept: `application/vnd.hmrc.${apiVersion}+json`,
    ...hmrcConfig.getFraudHeaders(req),
  };
  // Only set a JSON Content-Type when there is actually a body (see gotcha 3).
  if (data !== null && data !== undefined) {
    headers['Content-Type'] = 'application/json';
  }
  const res = await axios({ baseURL: hmrcConfig.baseUrl, method, url: path, headers, data });
  return res.data;
}

A great first call is "list this person's businesses", which uses their National Insurance number (NINO) and the Business Details API. It's read-only, so it's a safe way to confirm your token and headers are accepted:

// GET /individuals/business/details/{nino}/list  (Business Details API v2.0)
const businesses = await request(
  'GET',
  `/individuals/business/details/${nino}/list`,
  accessToken,
  req,
  null,
  '2.0',
);

Once that returns, the natural next call is obligations: what quarterly updates are due and when. This one is on a newer API version, which is the perfect lead-in to the gotchas:

// GET /obligations/details/{nino}/income-and-expenditure  (Obligations API v3.0)
const obligations = await request(
  'GET',
  `/obligations/details/${nino}/income-and-expenditure`,
  accessToken,
  req,
  null,
  '3.0',
);

To test these in the sandbox, you create a fake taxpayer using HMRC's "Create Test User" API, which hands you a NINO and Government Gateway credentials to log in with during the OAuth flow.

Common Gotchas that Will Cost You an Afternoon

A few traps catch nearly everyone the first time:

1. Pin the API Version, or Get a 406.

Different HMRC APIs live at different versions: Business Details is on 2.0, Obligations on 3.0, the calculation APIs on later versions again. The version lives in the Accept header (application/vnd.hmrc.3.0+json). Send the wrong version, or forget the header, and HMRC replies 406 Not Acceptable. When a call mysteriously fails, check the version first.

2. The state Token is Single-Use.

Validate it, then delete it immediately, before you do anything else. If you leave it lying around, you've weakened the CSRF protection it exists to provide. Expire stale ones too.

3. Don't send Content-Type: application/json on a bodyless GET.

This one is genuinely surprising. HMRC's edge (CloudFront) rejects a GET that carries a JSON Content-Type with no body as a 403 Bad request, which can break every read endpoint at once. Only set Content-Type when there's an actual body to send, as in the snippet above.

4. Subscribe Your App to Each API.

As mentioned in step 1, an unsubscribed API returns 403, which reads like an auth problem but is not.

5. The Redirect URI Must Match Exactly.

A trailing slash or http versus https mismatch produces an opaque error on the consent screen. Copy it, don't retype it.

Where to Go Next

That's the whole spine: register a sandbox app and subscribe it, run the OAuth Authorization Code flow to get tokens, attach fraud prevention headers, and make versioned JSON calls.

From here, the rest of MTD is more of the same: submit the cumulative quarterly figures, trigger a tax calculation, read the result, and eventually submit the final declaration. Each is another endpoint with the same two gates you've already cleared.

The kindest thing I can tell a beginner is to lean on HMRC's own tooling: the sandbox, the test users, and especially the fraud-header validator. Drive each of those to a clean result and the integration stops feeling like a regulatory maze and starts behaving like an ordinary, if unusually careful, REST API.

I work on TapTax, a Making Tax Digital app for UK sole traders, which is where I picked up the details above.

About the author: Solomon Amos is the founder of TapTax and built its HMRC Making Tax Digital integration. He has spent the last three years as a lead technical architect on HMRC digital modernisation programmes, and holds a PhD in engineering, with research in machine learning. You can find him on LinkedIn.