Authentication

The Service API (api.trancent.dev/v1) uses API keys with HMAC-SHA256 request signing. Every request to a /v1/* endpoint must include the three headers described below.

API key format

tk_live_<secret>   # production keys
tk_test_<secret>   # test mode keys

API keys are org-scoped — the organization context is implicit from the key, so you never need to pass an org ID separately. Keys are created in the Trancent dashboard under Settings → API Keys. The raw secret is shown only once at creation time; only a derived hash is stored server-side.

Required headers

Header	Description
`Authorization`	`Bearer tk_live_<secret>` (or `tk_test_…` for test mode)
`X-Timestamp`	Unix timestamp in seconds (must be within ±5 minutes of server time)
`X-Signature`	HMAC-SHA256 of the canonical string (see below), hex-encoded

Signing algorithm

Construct the canonical string by joining four components with newlines:

<X-Timestamp>
<METHOD>
<path>
<body>

Component	Value
`X-Timestamp`	The same Unix-seconds value sent in the header
`METHOD`	Uppercase HTTP method — `GET`, `POST`, etc.
`path`	URL path including query string (e.g. `/v1/ledgers/abc/journal-entries?limit=10`)
`body`	Raw request body string, or empty string for requests without a body

Sign the canonical string with HMAC-SHA256 using the raw API key secret as the key, then hex-encode the result:

import { createHmac } from 'crypto';

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify(payload);
const canonical = [timestamp, 'POST', path, body].join('
');

const signature = createHmac('sha256', apiKeySecret)
  .update(canonical)
  .digest('hex');

Replay protection

Requests with an X-Timestamp more than ±5 minutes from server time are rejected with 401. Use an Idempotency-Key header on mutating requests for safe retries.

Error responses

Status	Meaning
`401`	Missing or invalid API key, bad HMAC signature, or expired timestamp
`403`	Valid key but insufficient permissions for the requested resource

All errors follow the RFC 9457 problem detail format.