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

1. Navigate to API Keys in the main menu
2. Click Create New API Key
3. 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
4. Set an expiration date (default is 90 days)
5. Click Create API Key

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

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