API access
HTF v0.1.5 supports personal API keys and service-account keys for reporting and operational integrations, with 48 documented operations. Read and write actions have separate permissions. Key creation still defaults to read-only access; select additional permissions explicitly when issuing an appropriate key. Existing keys retain their grants.
Open the customer API reference for authentication, supported endpoints, and request formats, or download the OpenAPI specification. For a self-hosted deployment, open /docs/api/ on its API server. The station's own API key is a separate credential for runtime operations.
Personal keys
Open My Account → Personal API Keys to create a key. Choose an organisation, the projects it may access, the permissions it needs, and an expiry. A personal key remains limited by its owner's current organisation membership and project grants. Save the value when it is shown; it will not be displayed again.
Service accounts
Organisation administrators can manage service accounts in Identity → Service Accounts. Use one for an unattended integration rather than a person's key. Restrict its project scope and permissions, and revoke the token when the integration is retired.
Available permissions
| Permission | Access |
|---|---|
projects:read | Discover selected projects. |
projects:create | Create a project; requires organisation-level delegation. |
projects:update | Rename a project. |
projects:delete | Delete a project. |
groups:read | List station groups. |
groups:manage | Create and delete non-default station groups. |
stations:read | Read station identity and status. |
stations:delete | Delete a station. |
runs:read | Search runs, inspect stage results, and read structured reports and DUT captures. |
runs:start | Start single runs and batches on an online station. |
runs:abort | Abort a run. |
logs:read | Read paginated run logs; also requires runs:read. |
firmware:read | Read application and firmware version metadata. |
firmware:download | Download firmware binaries. |
firmware:write | Create or update applications, versions, and tags, and upload binaries. |
id-pools:read | Read ID-pool variable metadata. |
id-pools:values:read | Read ID-pool rows and allocated or reserved values. |
id-pools:manage | Create or rename variables, import or add rows, and edit, prioritise, or remove rows. |
assignments:read | Read assignment history. |
assignments:release | Explicitly release an assignment. |
Grant only the permissions the integration needs. Starting a run does not grant result access; uploading firmware does not grant download access; managing an ID pool does not grant access to its existing values. All requests remain constrained by the key's project selection and current access. Service-account keys cannot exceed their account's projects or permissions.
Personal keys with projects:create require current organisation Owner or Admin membership. Service accounts need that permission on both the account and key. A newly created project is not automatically added to their selected projects; update the service account's scope if needed, then issue an appropriately scoped key.
Production and staging support all 20 permissions for both personal and organisation/service-account keys. Production's missing 16 provider permission definitions were added on 2 November 2026, preserving existing key grants, roles, and read-only creation defaults. Self-hosted operators must enable the definitions for both key types in WorkOS before issuing keys that request them. This is provider configuration; it does not require a WorkOS SDK or login upgrade.
Customer keys cannot create stations, read or edit runtime YAML, manage station secrets or credentials/certificates, provision Infuse devices, or allocate/commit station variables. Human identity, roles/grants, kiosk accounts, and key/service-account administration remain outside this API. Use an authorised human session for security setup and the station credential for runtime-only operations.
Read history and download test data
GET /api/v1/stations/{stationId}/runs remains a compatibility array of the 100 most recent runs. It is not a total-count or full-history endpoint. Portal totals use analytics and portal history uses paginated endpoints; these portal routes are not automatically available to customer keys. Use the published customer reference to choose supported integration routes.
Customer keys can page through project runs at GET /api/v1/projects/{projectId}/runs using runs:read. For bulk evidence, these endpoints return items and nextCursor:
Endpoint suffix after /api/v1/projects/{projectId} | Data and permissions |
|---|---|
/log-runs | Run index with stage metadata and retained-line counts; runs:read and logs:read. |
/logs | Individual retained log entries; runs:read and logs:read. |
/key-values | Captured observations, including repeated keys and verification history; runs:read. |
For these bulk endpoints, set limit to 1–500 (default 200), then pass nextCursor as cursor until it is null. Keep the project and filters unchanged between pages. Read console output through /logs or the per-run log endpoint; /log-runs supplies the run index, not embedded log bodies.
The historical stage catalog at /api/v1/projects/{projectId}/log-stages requires runs:read and logs:read. It uses items and nextOffset: pass nextOffset as offset until it is null, with the same 1–500 limit range (default 200).
The data is live: export completed tests after their data has finished arriving. See Results and logs for the portal's complete-run and selected-stage downloads.
Read structured reports and captures
These project endpoints accept keys with runs:read:
| Endpoint | Result |
|---|---|
GET /api/v1/projects/{projectId}/runs/{runId}/report | Stage results, observations, and capture warnings without console logs. |
GET /api/v1/projects/{projectId}/dut-observations?dutId=DUT-01&offset=0 | A page of 50 historical observations for the DUT. |
GET /api/v1/projects/{projectId}/dut-records?search=IDENTIFIER&offset=0 | DUT summaries matching a DUT ID or current/historical captured value. |
Report and run-detail responses never embed raw logs for customer API keys. Report responses have empty logs and logsIncluded: false. Use log endpoints with both logs:read and runs:read for console output.
Without id-pools:values:read, DUT records contain captures only: values and reservations are empty, and DUTs known only through ID-pool assignments are omitted. Reading pool values requires that additional permission and the applicable project access. For an organisation Member's personal key, captured-data access additionally requires the owner's current dut-records:read permission. Changing a custom role changes that owner's key ceiling; granting a key permission cannot expand the owner's human access.
See DUT capture history for the meaning of verified observations and identifier change flags.
Release source: HTF v0.1.5 and permission design at the released revision (repository access required).