API Authentication Tuesday Jul 15, 2025 Rowan Easter-Robinson LinkedIn 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 requests) Creating API Keys Navigate to API Keys in the main menu Click Create New API Key Select the appropriate role: Choose Read-only for applications that only need to view data Choose Read-write for applications that need to modify data Set an expiration date (default is 90 days) 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, include it in the Authorization header: Authorization: Bearer YOUR_API_KEY Example Request curl -X GET "https://your-org.trackmymachines.com/api/v1/step_events" \ -H "Authorization: Bearer YOUR_API_KEY" 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 Limit permissions: Always use the most restrictive role that meets your needs Rotate keys regularly: Create new keys and deprecate old ones periodically Set expiration dates: Use the shortest practical expiration period Monitor usage: Regularly review which applications are using your API keys Revoke unused keys: Delete API keys that are no longer needed Warning Never share your API keys or commit them to version control systems. Treat them like passwords.
Clocking on and Clocking off jobs Tuesday Jul 15, 2025 Rowan Easter-Robinson LinkedIn Step Events The step events endpoint allows you to retrieve, create, and finish jobs in your manufacturing process. TrackMyMachines uses this data to produce reports, calculate estimated finish times and alert you when your machines run jobs exceeding the quoted time from your ERP system. Permissions Endpoint Method Read-only Access Read-write Access Description /api/v1/step_events GET ✅ ✅ Retrieve step events /api/v1/step_events POST ❌ ✅ Create a new step event, and finish it with an optional parameter Endpoints GET /api/v1/step_events Retrieves step events based on the provided filters. Required Role: Read-only or Read-write Query Parameters: from: Start of the time range for filtering events (default: current week) to: End of the time range for filtering events (default: current week) machine_ids: Comma-separated list of machine IDs to filter events by Example Request: curl -X GET "https://your-org.trackmymachines.com/api/v1/step_events?from=2025-05-20&to=2025-05-27&machine_ids=1,2,3" \ -H "Authorization: Bearer YOUR_API_KEY" Example Response: [ { "id": 15610, "tzrange": "2025-06-18 09:00:00 UTC...Infinity", "started_at": "2025-06-18T09:00:00.000Z", "ended_at": null, "eventable_type": "Step", "eventable_id": 709, "machine_id": 6, "cycle_count": 273, "minimum_cycle_time": 33, "median_cycle_time": 46, "maximum_cycle_time": 64, "total_in_cycle_time": 12833, "part_count": 243, "time_to_first_part_count": 1637024, "minimum_time_between_part_counts": 135, "maximum_time_between_part_counts": 1127, "median_time_between_part_counts": 145, "load_time": 89, "total_part_count_time": 37568, "total_dead_time": 4763, "metadata": { "work_order_id": "", "quantity_expected": "15" }, "machine_name": "Machine 1", "display_name": "1677723 Op10", "range": "2025-06-18 09:00:00 UTC...Infinity" }, { "id": 18315, "tzrange": "2025-06-27 16:23:00 UTC...Infinity", "started_at": "2025-06-27T16:23:00.000Z", "ended_at": null, "eventable_type": "Step", "eventable_id": 709, "machine_id": 9, "cycle_count": 273, "minimum_cycle_time": 10, "median_cycle_time": 46, "maximum_cycle_time": 64, "total_in_cycle_time": 12916, "part_count": 242, "time_to_first_part_count": 832793, "minimum_time_between_part_counts": 135, "maximum_time_between_part_counts": 1135, "median_time_between_part_counts": 146, "load_time": 89, "total_part_count_time": 37543, "total_dead_time": 4873, "metadata": { "work_order_id": "", "quantity_expected": "25" }, "machine_name": "Machine 4", "display_name": "1677723 Op10", "range": "2025-06-27 16:23:00 UTC...Infinity" } ] POST /api/v1/step_events Clock on a job, creating a “Step Event in the timeline”. Clocking on a job with parts, routes or steps that don’t exist will create them in TMM automatically. This endpoint is idempotent across requests with the same body, meaning you can retry requests without fear of creating duplicate events. It’s possible to start a job with this endpoint that hasn’t been finished yet. To finish a job that’s been started, send the same minimum required parameters along with the optional finish parameter. Required Role: Read-write Request Body: { "step_event": { "machine_display_name": "Machine1", "start": "2025-05-27T10:00:00Z", "user_email": "user@example.com", "part_unique_identifier": "PART123", "part_issue": "A", "recipe_version": "1", "step_number": "10", "step_expected_cycle_time": 120, "step_expected_setup_time": 30, "qty_expected": 5, "wo_number": "WO-123" } } Required Fields: machine_display_name: Display name of the machine start: Start timestamp (ISO8601) user_email: Email of the user associated with the event part_unique_identifier: Unique identifier for the part recipe_version: Version of the recipe step_number: Step number in the recipe Optional Fields: part_issue: Part issue number finish: Finish timestamp (ISO8610) step_expected_cycle_time: Expected cycle time (seconds) step_expected_setup_time: Expected setup time (seconds) qty_expected: Expected quantity qty_made: Quantity made qty_scrapped: Quantity scrapped wo_number: Work order number Example Response: { "event": { "machine_id": 6, "range": "2025-05-27 10:00:00 UTC...", "eventable_type": "Step", "eventable_id": 3092, "ending_type": "manual", "id": 7785, "deleted_at": null, "metadata": { "qty_expected": 5, "wo_number": "WO-123" }, "created_at": "2025-05-27T10:01:45.397Z", "updated_at": "2025-05-27T10:01:45.397Z", "user_id": 3, "tzrange": "2025-05-27 10:00:00 UTC...", "machine_name": "Machine 1", "display_name": "PART123 Op10" }, "step": { "id": 3092, "machine_id": null, "recipe_id": 2443, "number": "10", "description": null, "created_at": "2025-05-27T10:01:45.369Z", "updated_at": "2025-05-27T10:01:45.369Z", "expected_cycle_time": 120, "expected_setup_time": 30 }, "recipe": { "id": 2443, "organisation_id": null, "part_id": 2348, "description": null, "created_at": "2025-05-27T10:01:45.363Z", "updated_at": "2025-05-27T10:01:45.363Z", "version": 1 }, "part": { "id": 2348, "unique_identifier": "PART123", "organisation_id": 3, "description": null, "created_at": "2025-05-27T10:01:45.358Z", "updated_at": "2025-05-27T10:01:45.358Z" } } Error Handling Machine Not Found { "error": "Machine not found" } User Not Found { "error": "User not found" } No Active Step Event { "error": "No active step event found for this machine" } Invalid End Timestamp { "error": "Invalid end timestamp" } Read-only API Key Attempting Write Operation { "error": "This API key does not have write permissions" } Record Invalid Record invalid means that validations for the record have not passed, the error message will detail the reason for vaildation failure { "error": "Validation Failed: Error message" }
Setting up your TrackMyMachines account Tuesday Jul 15, 2025 Rowan Easter-Robinson LinkedIn Your TrackMyMachines account You should have an account set up in touch with support at support@trackmymachines.com Add a machine to your TrackMyMachines account Go to Manage -> Machines Click “New Machine” Fill in the name of the machine Where it says “Data Source” fill in the code in bold on the front of your device Click “Create Machine”
