Authentication

Generate an API token and authenticate requests with a Bearer header.

Updated October 29, 2026

Prerequisites: You need an account with access to the organization you want to query.

Generate an API token

API tokens are personal — they’re created from your own account, not an organization admin area, and each token carries the same access as the user who created it.

Click your avatar at the bottom of the sidebar → Setting, then open the API Tokens tab.
Click New API Token.
Enter a name that identifies the integration (e.g., “CAM Plugin”, “ERP Sync”).
Click Create. The token is shown once — copy it immediately. It will not be shown again.

You can create several tokens and revoke any of them from the same screen.

Authenticate requests

Include the token in the Authorization header of every request:

Authorization: Bearer <your-token>

Requests without a valid token receive a 401 Unauthorized response, with a WWW-Authenticate: Bearer header on the response:

{ "errors": ["Access denied"] }

Find your organization ID

Most endpoints require an organization_id path parameter. Retrieve it from:

GET /v1/organizations
Authorization: Bearer <your-token>

Response — a map of organization name to ID:

{
  "Acme Manufacturing": 12,
  "Acme Tooling": 15
}

Use the numeric ID in all subsequent requests:

GET /v1/organizations/12/machines
Authorization: Bearer <your-token>

Authorization scoping

Having a valid token for the right organization doesn’t guarantee you see every record in it. Access is further scoped by your role for each resource type within that organization:

Site admins, and users with an admin or manager role on a resource, see every matching record in the organization.
Users with a user role on a resource are scoped to only the records they created (user_id matches the token’s bearer).

This scoping applies per resource type (e.g., your role on parts and your role on machines are independent) and is enforced on every list and detail endpoint, not just on write actions.

Error responses

Requests fail with:

Status	Meaning
`401 Unauthorized`	Token missing/invalid, or the token’s bearer is not authorized for this action — both cases use `401`, not `403`. The error message differs: a missing/invalid token gets `"Access denied"`; an authorization failure gets `"You are not authorized to perform this action"`. An `organization_id` that doesn’t exist gets the authorization failure, as an organization the token cannot reach
`404 Not Found`	Record does not exist or belongs to a different organization
`422 Unprocessable Entity`	Validation failed — response body contains field errors

See Errors for the complete error format, including an inconsistency in the 404 response body worth knowing about.