Authentication

Authentication is how the Engine API knows a request is yours. Every call carries an API key that identifies your organization, and the API reads that key to decide what the request may do and whose usage to record against it.

It matters because that key is the only thing between your account and anyone who gets hold of it. This page covers how to attach a key to a request, how to store it so it does not leak, and how to check that one works.

Authenticated Engine API operations use a Toolpath API key as a Bearer credential:

Authorization: Bearer YOUR_API_KEY

Description:

A header is extra information attached to a request. This one carries your key. Bearer means whoever holds the key gets in, so treat it like a password. The SDKs add this header for you.

Create and revoke keys from API Keys in the Toolpath Portal — the Quick Start Guide walks through it. The complete key is shown only when it is created. Never put it in logs, screenshots, or client-side browser code.

export TOOLPATH_API_KEY='YOUR_API_KEY'

curl https://api.toolpath.com/v1/jobs \
  --header "Authorization: Bearer ${TOOLPATH_API_KEY}"

Description:

An environment variable is a named value your shell holds. Keeping the key there instead of in the code means you can share or commit the script safely. It lasts until you close the terminal.

Keys begin with tp_. The prefix displayed later in Portal is only an identifier and cannot be used to authenticate. Revoking a key takes away its access.

Keeping a key out of your code

A key should never appear in a file you commit. The usual pattern is four steps:

1. Put the key in a .env file beside your code:

   TOOLPATH_API_KEY=tp_your_key_here

2. Add .env to .gitignore before the file exists, not after.

3. Commit a .env.example alongside it holding the variable name and a placeholder, so a teammate knows what to set without a real key ever being committed. Both SDK examples ship one.

4. Read the value from the environment at runtime. Your code refers to the variable name; the value lives only in .env.

For deployed code the same principle applies with a different store: GitHub Actions secrets, AWS Secrets Manager, or whatever your platform provides, injected at runtime. Never bake a key into a build artifact — anything shipped to a browser is readable by anyone who loads the page.

A key you use only for testing is still a key. It can still be scraped, still bills to your organization, and still shows an attacker the shape of your setup.

Description:

If a key does get committed, deleting it in a later commit is not enough — the value stays in the repository's history and in every clone anyone has made. Regenerate or revoke it in Portal. That is the only fix.

Check that a key works

POST /v1/keys/validate reports the status of the key in the Authorization header and nothing else. An active key returns 200; a missing, revoked, expired, or unknown key returns 401. Both answer with the same shape, so an integration can confirm a key and show why it failed.

curl --request POST https://api.toolpath.com/v1/keys/validate \
  --header "Authorization: Bearer ${TOOLPATH_API_KEY}"

{ "valid": true, "status": "active" }

status is one of active, revoked, expired, or invalid.

Description:

Run this first. It changes nothing, so success confirms your key and your setup before anything else can go wrong. A 401 means the key is not usable — check you copied all of it and that it is still active in Portal.

What a key may do

Every key carries an access grid: read and write access, granted separately, in each area of the API.

Area	Covers
Core API	Uploads, part display (mesh, thumbnail), holders, and jobs
DFM API	Part analysis, feature datasheets, and plans (including plan reads)
Quoting API	Toolpaths and machining time (including their reads)

Early access

Machining plans and toolpath calculation — creating, listing, and reading plans, calculating toolpaths, and reading toolpath results and machining time — are available now but still gaining functionality; planned additions include plan constraints and specifying material and stock, among others. Breaking changes still follow the API major version, so you can build against them today. In the API reference these operations are marked x-toolpath-experimental.

You choose the grid under Access when you create the key, and you can change it later from the key's menu on the API Keys page. Every box is ticked on a new key. Write includes read, and core read is always on so a key can follow the jobs it starts. Uploading a part is a core write, so a Quoting key needs core write to upload the part it quotes.

GET reads; every other method writes. In the API reference every operation states its area in x-toolpath-product (core, dfm, or quoting) and whether the call is billed in x-toolpath-metered. Reads are free but still belong to a product: reading a plan needs DFM access, and reading toolpaths needs Quoting.

A key used somewhere it has no access is refused with 403 and the code product_mismatch. A key that may only read an area, used for a write there, is refused with 403 and the code read_only_key. Either response names the area and what the key may do instead. The key itself is still valid, so retrying with it changes nothing; widen its access in the Portal.

Description:

Think of each area as a room with a door. Read lets a key look in; write lets it change things. Core is the hallway — every key can look down it, and a key with core write can bring parts in.

Public endpoints

The health endpoint and GET /v1/openapi.json are public. All other current operations require the Bearer API key.