Skip to main content

API Authentication

All API requests to TrackMyMachines require authentication using API keys. Each API key is associated with an organization and has specific permissions based on its role.

API key roles​

TrackMyMachines supports two types of API key roles:

  • Read-only: can only access data retrieval endpoints (GET requests)
  • Read-write: can both read data and make changes (GET, POST, PATCH, DELETE)

Creating API keys​

  1. Navigate to API Keys in the main menu
  2. Click Create New API Key
  3. Select the appropriate role:
    • Read-only for applications that only need to view data
    • Read-write for applications that need to modify data
  4. Set an expiration date (default is 90 days)
  5. Click Create API Key
warning

The API key will only be displayed once upon creation. Make sure to copy it to a secure location immediately.

Using API keys​

To use an API key in your requests, send it in either of these headers:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

They are equivalent. X-API-Key takes the key on its own, with no Bearer prefix, which suits tools that write a credential into a single header verbatim (Power Automate, for example). If a request sends both, X-API-Key is used.

Example request​

curl -X GET "https://your-org.trackmymachines.app/api/v1/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL​

Every endpoint is served on your organisation's own subdomain:

https://your-org.trackmymachines.app/api/v1/...

Replace your-org with the subdomain you sign in at. On this host the key must belong to that organisation; a key from another organisation is refused with 401 Wrong organisation.

The jobs and machines endpoints are also served on one shared host, the same for every organisation:

https://api.trackmymachines.app/api/v1/jobs
https://api.trackmymachines.app/api/v1/machines

There the API key alone decides which organisation the request is for. Use it when a tool needs a single fixed URL for every customer, such as a Power Automate connector. The other endpoints are only on your organisation's subdomain.

Error responses​

When using an API key with insufficient permissions, you'll receive a 403 Forbidden response:

{
  "error": "This API key does not have write permissions"
}

Other common error responses:

  • 401 Unauthorized: invalid or expired API key
  • 404 Not Found: resource not found
  • 422 Unprocessable Entity: invalid parameters

Security best practices​

  1. Limit permissions: always use the most restrictive role that meets your needs
  2. Rotate keys regularly: create new keys and deprecate old ones periodically
  3. Set expiration dates: use the shortest practical expiration period
  4. Monitor usage: regularly review which applications are using your API keys
  5. Revoke unused keys: delete API keys that are no longer needed
warning

Never share your API keys or commit them to version control. Treat them like passwords.