# BuildTrace documentation

> What BuildTrace is and who it is for; links into the sections.

BuildTrace tracks a hardware product from the part to the device in the field. You define parts, revisions and bills of materials. You stock materials, run build orders, and produce units. Each unit gets a serial number and an immutable as-built record that lists the exact components, lots and changes it was built with. After it ships, BuildTrace keeps following the unit: firmware, repairs and replaced parts go into an as-maintained record, so you can always say what a unit is made of today and what it was made of when it left your floor.

It is for the people who run a small hardware operation: admins who set up the workspace, engineers who define products, production managers and operators who build them, quality and compliance staff who inspect and recall them, and the teams who ship and support the devices.

## Where to start

- **Getting started.** Create a workspace, add your first product, build one unit and open its record. Start with [Create a workspace](https://buildtrace.eu/docs/getting-started/create-workspace.md).
- **Concepts.** How parts, revisions, BOMs, change orders, build orders, inventory, serials and devices fit together. Start with [Parts and revisions](https://buildtrace.eu/docs/concepts/parts-and-revisions.md).
- **Guides.** Step-by-step tasks: [device check-in](https://buildtrace.eu/docs/guides/device-check-in.md), [scope a recall](https://buildtrace.eu/docs/guides/scope-a-recall.md) and [SBOM export](https://buildtrace.eu/docs/guides/sbom-export.md).

## Use the API

The REST API is in beta: endpoints and fields may change before 1.0. The public contract is the set of operations meant for integrations; the web app uses further endpoints that are not part of it.

Integrations sign in as a service account. A workspace admin creates one in Settings and gets a `clientId` and a `clientSecret`. Exchange them for an access token with `POST /api/auth/token`:

```bash
curl "https://app.buildtrace.eu/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"grantType":"client_credentials","clientId":"'"$CLIENT_ID"'","clientSecret":"'"$CLIENT_SECRET"'"}'
```

The response has an `accessToken`. Send it as `Authorization: Bearer <token>`. Each operation needs one scope, listed with it in the API reference, and the service account only gets the scopes the admin picked when creating it.