Developer API & Integration

MFC Safe Pty Ltd Developer API & Integration Guide Title: MFC Safe Developer API & Integration Guide Version: 1.0 Effective Date: 2 June 2025 Next Review Date: 2 June 2026

---

1. Purpose

This document provides technical guidance for developers and partners integrating with the MFC Safe PaaS platform. It outlines authentication, API standards, payload structures, webhook implementations, and error handling required to interact with the Didge platform.

---

2. API Overview

• RESTful JSON-based APIs over HTTPS

• Base URL: https://api.didge.mfcsafe.com/v1/

• All requests must use TLS 1.2 or above

---

3. Authentication

• OAuth 2.0 authorization using Auth0

• Required scopes: read:forms, write:data, manage:webhooks

• All API requests require a Bearer token in the header: Authorization: Bearer <access_token>

• Tokens expire after 12 hours; refresh token flow supported

---

4. Webhooks

• Supports event-driven POST requests from Didge

• Webhook setup via API or Admin Portal

• Supported events:

  • form.submission.completed

  • sensor.alert.triggered

  • user.invite.accepted

• Webhook signature: HMAC SHA-256 with shared secret header X-MFC-Signature

---

5. Core Endpoints

5.1 Form Submission

• POST /submissions Submit or update compliance forms

• GET /submissions/{id} Retrieve specific submission by ID

5.2 Sensor Data API

• GET /sensors List registered sensors

• GET /sensors/{id}/readings Retrieve time-series readings

5.3 User Management

• POST /users/invite Invite user to site

• PATCH /users/{id} Update user roles or site access

---

6. Data Payload Standards

• JSON schema validated with versioning (v1, v2)

• Timestamps in ISO 8601 UTC format (e.g., 2025-06-02T03:12:00Z)

• Units standardized (e.g., Celsius, %RH)

• Sensor payload includes:

{
  "sensor_id": "abc123",
  "type": "temperature",
  "value": 4.3,
  "timestamp": "2025-06-02T03:12:00Z"
}

---

7. Error Handling

• Standard HTTP status codes used

• 4xx = Client error (e.g., 401 Unauthorized, 422 Validation Error)

• 5xx = Platform error

• Error object format:

{
  "error": "Validation failed",
  "field": "email",
  "code": 422
}

---

8. SDKs and Tools

• JS SDK for form embedding and submission

• Python SDK for sensor API integration

• CLI tool for admin operations (token generation, webhook config)

---

9. Support & Contact

• Dev Portal: https://developer.mfcsafe.com

• API Status: https://status.mfcsafe.com

• Email: [e-mail]

---

End of Guide