Authentication & API keys

How keys work#

• A key belongs to one TruTec workspace and can only read or change that workspace's data.
• Workspace owners create and revoke keys in Settings › API keys.
• A key is shown once, when you create it. We store only a salted hash, so we can't show it again or recover it. Lost a key? Revoke it and make a new one.
• Keys start with sk_. The first 11 characters (for example sk_4fQ9xT2b) are the key's public prefix: it's what you see in Settings and what to quote to support.
• A workspace can have as many active keys as you need. Give each system its own key so you can revoke one without touching the others.
• Connecting ChatGPT or Claude by signing in with TruTec creates a key for that assistant, read only or read and change as the owner picks (AI assistants). It's listed and revoked like any other key.
• API access comes with plans that include it. If the plan or billing lapses, calls return 403 or 402 with a message saying why (Errors).

Send the key#

Put the key in the X-API-Key header on every request:

curl https://trutec.ai/api/v1/jobs \
  -H "X-API-Key: sk_your_api_key_here"

import os
import requests

API = "https://trutec.ai/api/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["TRUTEC_API_KEY"]

jobs = session.get(f"{API}/jobs", timeout=30).json()

// Node 18+, server-side only
const API = "https://trutec.ai/api/v1";
const res = await fetch(`${API}/jobs`, {
  headers: { "X-API-Key": process.env.TRUTEC_API_KEY },
});
const jobs = await res.json();

The MCP server also accepts Authorization: Bearer sk_..., because some AI clients can only send that header. The REST endpoints read X-API-Key.

Call from your servers only#

API keys are secrets with access to your company's data. Call the API from your backend, a scheduled job or a serverless function, and keep the key in an environment variable or a secrets manager. Never put a key in browser JavaScript, a mobile app or a public repository. If a key leaks, revoke it in Settings › API keys: revocation takes effect on the next request.

Permissions#

Each key carries a set of permissions, and every endpoint checks them. A call without the permission it needs returns 403 and names what's missing.

Permission	Lets the key	Default
Read measurements	Measure sites, rate pavement condition, and read measurement results, saved takeoffs and imagery	On
Read jobs	Read customers, sites, jobs, estimates, job costing, events, webhook deliveries and exports	On
Write jobs	Create and update customers, sites and jobs; manage webhooks; redeliver and replay events	On for read & write keys
Write measurements	Save a measurement onto a job as a takeoff, rename takeoffs	On for read & write keys
Delete records	Delete or archive customers, sites, contacts, photos, files, takeoffs and other records (needs the matching write permission too)	Off
Partner	Manage the workspaces of a software platform's own customers (Partner API)	Off, granted by TruTec

Keys created in Settings › API keys can read and write (Read measurements, Read jobs, Write jobs, Write measurements), and can't delete. For reporting, warehouse syncs and AI assistants a read-only key is the safer choice: it can see everything and change nothing. Ask us and we'll make any key read-only.

Delete records is off for every new key. If your integration needs to delete or archive records, email [email protected] from a workspace owner's address with the key's prefix and we'll turn it on for that key.

Each endpoint's page lists the permission it needs.

Test and production keys#

Keep test traffic away from production data with a sandbox workspace: a separate TruTec workspace with sample customers, sites, jobs and estimates. Its keys can only see sandbox data, so a bug in your test code can't touch your real records. Switching to production means swapping the key, nothing else: the URL and the API are the same. See Sandbox & testing.

Name keys after where they run, for example erp-sync-prod, erp-sync-staging, warehouse-nightly, so the list in Settings tells you what each one is for.

Rotate a key#

Rotation needs no downtime, because a workspace can have more than one active key:

1. Create a new key in Settings › API keys (and ask us to match its permissions if the old key was read-only or could delete).
2. Deploy it to your system.
3. Confirm calls succeed with the new key.
4. Revoke the old key.

Rotate on a schedule that suits your security policy (every 90 days is common), whenever someone with access to the key leaves, and right away if a key may have leaked.

Authentication errors#

Status	error	What it means
401	Missing API key	No X-API-Key header
401	Invalid API key	Wrong key, revoked key, or a key whose workspace no longer exists
403	Plan upgrade required	The workspace plan doesn't include API access
403	API access disabled	API access is turned off for the workspace. Contact support
402	Subscription past due / Subscription inactive	Billing needs attention. Access comes back as soon as it's fixed
403	Trial expired / Subscription canceled	The workspace has no active subscription
429	API usage limit exceeded	This key reached the call cap set on it

Every error body has the same shape:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}