Authentication

Authentication, rate limiting, and API conventions for the TaxMTD REST API.

Base URL#

TaxMTD provides two API surfaces:

Surface	Base URL	Auth method
Session API	`https://taxmtd.uk/api`	Session cookies
Public API (v1)	`https://taxmtd.uk/api/v1`	API key (Bearer token)

The Session API is used by the TaxMTD web app and requires login cookies. The Public API is designed for external integrations, scripts, and third-party apps using API keys.

API Key Authentication (Recommended)#

API keys provide stateless, token-based access to the Public API. Generate keys from Settings → API Keys in your TaxMTD dashboard.

Using Your API Key#

Pass the key as a Bearer token in the Authorization header:

const data = await fetch('https://taxmtd.uk/api/v1/transactions', {
  headers: { 'Authorization': 'Bearer tmtd_your_api_key_here' }
}).then(r => r.json())

Available v1 Endpoints#

Method	Endpoint	Description
`GET`	`/api/v1/transactions`	List transactions
`GET`	`/api/v1/invoices`	List invoices with line items
`POST`	`/api/v1/invoices`	Create invoice
`GET`	`/api/v1/bills`	List bills with line items
`POST`	`/api/v1/bills`	Create bill
`GET`	`/api/v1/contacts`	List contacts
`POST`	`/api/v1/contacts`	Create contact
`GET`	`/api/v1/products`	List products
`POST`	`/api/v1/products`	Create product
`GET`	`/api/v1/employees`	List employees
`GET`	`/api/v1/categories`	List expense categories

Pagination#

All GET endpoints support limit and offset query parameters:

curl "https://taxmtd.uk/api/v1/transactions?limit=25&offset=50" \
  -H "Authorization: Bearer tmtd_your_api_key_here"

limit - Number of records to return (default 50, max 200)
offset - Number of records to skip (default 0)

API Key Scoping#

API keys can optionally be scoped to a specific entity (business). When scoped, all queries automatically filter to that entity's data. Unscoped keys return data across all entities owned by the key creator.

Managing API Keys#

// List keys (full key is never returned)
const keys = await $fetch('https://taxmtd.uk/api/api-keys')

// Create a new key
const { data } = await $fetch('https://taxmtd.uk/api/api-keys', {
  method: 'POST',
  body: { name: 'My Integration', entity_id: '...' }
})
// data.raw_key is shown ONCE - save it immediately

// Revoke a key
await $fetch('https://taxmtd.uk/api/api-keys', {
  method: 'DELETE',
  body: { id: 'key-uuid' }
})

API keys are shown once when created. Store the key securely - it cannot be retrieved again. If lost, revoke and create a new one.

Session Authentication#

The session API is used internally by the TaxMTD web app. If you're building a browser-based integration that shares the same domain, you can use session cookies.

Obtaining a Session#

// Using $fetch (auto-includes cookies)
const data = await $fetch('https://taxmtd.uk/api/transactions')

Response Format#

All endpoints return JSON. Successful responses:

{
  "data": [...],
  "limit": 50,
  "offset": 0
}

Error responses:

{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: periodId"
}

HTTP Status Codes#

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request - invalid parameters
`401`	Unauthorised - no session or invalid API key
`404`	Not found
`405`	Method not allowed
`500`	Server error

Rate Limiting#

API key requests are rate-limited to 60 requests per minute per endpoint per key. Session API requests have per-endpoint limits documented on each endpoint page.

Content Types#

Method	Content-Type
GET	Query parameters
POST	`application/json`
PUT	`application/json`
DELETE	`application/json`

Was this page helpful? Share it.