Skip to main content

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.

Public endpoints​

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