Tokens and HTTP delivery

Releases are served over HTTP. You ask which release is newest, fetch its files, check them, and keep them: a release never changes, so you fetch each one once.

TokensCopy Anchor Link

Octroi issues tokens on request, with the licence. A token looks like tdk_live_ followed by 64 hex characters.

• It is shown once, when it is issued. Octroi keeps only its SHA-256 hash, so a lost token can't be shown again; ask for a new one.
• It is licensed either for countries named when it is issued, or for all, which covers every country in every release, including countries a later release adds.
• It expires, at most 366 days after it is issued, and Octroi can revoke it before then.

Send it on every release request as a bearer token:

GET /tax-data/v1/releases/latest HTTP/1.1
Authorization: Bearer tdk_live_…

Keep it on your server. Don't ship it to a browser.

Base URLCopy Anchor Link

The base URL is https://api.octroi.app. The paths below are relative to it. The samples read the token from OCTROI_TOKEN.

RoutesCopy Anchor Link

The newest releaseCopy Anchor Link

GET /tax-data/v1/releases/latest returns JSON, with Cache-Control: private, no-cache:

{
  "release": "2026-10-11",
  "publishedAt": 1791709200000,
  "countries": ["es"],
  "files": [
    {
      "path": "manifest.json",
      "sha256": "945133b76a245c7e727b173634affa45c3fdb75370005ba1ec284a5204fc0e8a",
      "bytes": 11670
    },
    {
      "path": "countries/es.json",
      "sha256": "52d6cbe6076e7090335194357d7a4f61755286a9f2039e91e7311b6ee848e982",
      "bytes": 106861
    }
  ],
  "token": { "expiresAt": 1823245200000 }
}

The list is cut to two files here. When release is one you already have, there is nothing to fetch.

A fileCopy Anchor Link

GET /tax-data/v1/releases/<id>/<path> returns one file of any release, newest or not, by its path in the release, such as /tax-data/v1/releases/2026-10-11/countries/es.json.

Send the ETag back in If-None-Match and you get 304 Not Modified with no body. Since files never change, a file you have already checked never needs fetching again.

The signing keyCopy Anchor Link

GET /tax-data/v1/signing-key returns the newest release's Ed25519 public key as an SPKI PEM, with Content-Type: application/x-pem-file and Cache-Control: public, max-age=3600. It needs no token. Before the first release it is a 404, release_not_found. Verify a release shows what to do with it.

What a token can fetchCopy Anchor Link

A token can fetch, from any release:

• every file that belongs to no country: manifest.json, manifest.json.sig, LICENSE.txt, changes.json, CHANGELOG.md and the schemas;
• countries/<cc>.json and vectors/<cc>.json for each country it is licensed for, or for every country with an all token.

Any other country's file is a 403, country_not_licensed. The manifest still lists every country, so you can see what a release holds.

ErrorsCopy Anchor Link

Errors are application/problem+json, with Cache-Control: no-store:

{ "status": 403, "code": "country_not_licensed" }

Error codesCopy Anchor Link

A 401 also carries WWW-Authenticate: Bearer.

Fetch the newest releaseCopy Anchor Link

This fetches every file the token can read into ./releases/<id>/ and checks each against the hash latest gives. sha256Hex is from Verify a release.

import { mkdir, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
import { sha256Hex } from "./verify";

const base = "https://api.octroi.app";
const headers = { Authorization: `Bearer ${process.env.OCTROI_TOKEN}` };

type Latest = {
  release: string;
  publishedAt: number;
  countries: string[];
  files: { path: string; sha256: string; bytes: number }[];
  token: { expiresAt: number };
};

async function get(path: string): Promise<Response> {
  const response = await fetch(`${base}${path}`, { headers });
  if (!response.ok) {
    const { code } = (await response.json()) as { code: string };
    throw new Error(`${response.status} ${code} for ${path}`);
  }
  return response;
}

const latest = (await (await get("/tax-data/v1/releases/latest")).json()) as Latest;
const dir = `./releases/${latest.release}`;
for (const file of latest.files) {
  const url = `/tax-data/v1/releases/${latest.release}/${file.path}`;
  const bytes = new Uint8Array(await (await get(url)).arrayBuffer());
  if ((await sha256Hex(bytes)) !== file.sha256)
    throw new Error(`${file.path} does not match its sha256`);
  await mkdir(dirname(`${dir}/${file.path}`), { recursive: true });
  await writeFile(`${dir}/${file.path}`, bytes);
}

The hashes in latest catch a broken download; they are not signed. Before you use the files, check the signature and the hashes in the signed manifest.

The same with curl:

curl -fsS -H "Authorization: Bearer $OCTROI_TOKEN" \
  "https://api.octroi.app/tax-data/v1/releases/latest"

curl -fsS -H "Authorization: Bearer $OCTROI_TOKEN" \
  "https://api.octroi.app/tax-data/v1/releases/2026-10-11/manifest.json" -o manifest.json