# Authentication

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

Source: https://support.toolingmetrics.com/en/api/authentication/
Updated: 2026-10-29

**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.

1. Click your avatar at the bottom of the sidebar → **Setting**, then open the **API Tokens** tab.
1. Click **New API Token**.
1. Enter a name that identifies the integration (e.g., "CAM Plugin", "ERP Sync").
1. 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:

```json
{ "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:

```json
{
  "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](https://support.toolingmetrics.com/en/api/errors/) for the complete error format, including an inconsistency in the `404` response body worth knowing about.