Use the read-only integration API

The integration API is a read-only endpoint for external systems.

It cannot perform web-app actions and it cannot act like a user login.

1) Authenticate

Use an environment variable to keep the secret out of commands:

export METRA_API_KEY=metra_live_<organisation-id>_<key-secret>

Send the full secret only in the header:

Authorization: Bearer <stored-secret>

Use the variable when you call the API:

curl -H "Authorization: Bearer $METRA_API_KEY" ...

<organisation-id> and <key-secret> are placeholders; use the real values from the key creation screen.

Do not use query strings, forms, cookies, URLs, logs, or source files to store keys.

Use a separate key for each external system and environment.

Each integration URL includes an organisation ID. The key owner must match that organisation.

2) Choose only needed scopes

Use the smallest scope set you need:

integration:equipment:read → equipment details and deployment history
integration:structure:read → clients, sites, locations
integration:calibration:read → requirements, due state, calibration events
integration:certificates:read → certificate metadata and approved downloads
integration:quality:read → out-of-tolerance items and quality workflow status

Download certificate files needs both calibration and certificate scope.

3) Use sync-safe paging

List endpoints use fixed ordering and cursor paging.

Read page 1 fully before moving the cursor.
If a request fails, retry the same request before moving on.
Use changed_since with an ISO8601 UTC timestamp to pull incrementally.

Even with changed_since, run a periodic full check to catch any temporary misses.

Treat IDs as opaque UUIDs and dates as UTC.

4) Handle errors and limits

For failures:

Re-authenticate on auth errors.
A not-found message may still mean “you do not have access in that scope.”
If 429, wait before retrying.
Keep request IDs for support.

Never log the full API key.

5) Rotate if needed