Manage Developer API Keys
+Obtain authentication tokens for integrating program modules and external query widgets.
+Generate New API Key
+Assign a friendly name to describe your application module usage.
+ + + + {isSystemUser ? ( +No Active API Keys
+You haven't generated any API keys yet. Create one on the left to start accessing endpoints.
+{key.name}
+
+ {showSecrets[key.id] ? key.apiKey : `${key.apiKey.substring(0, 8)}••••••••••••••••••••••••••••`}
+
+ Developer Sandbox Playground
+Query endpoints live and observe the robust read-only and anti-financial access controls.
+Configure Sandbox Query
+ +Simulate Security Audit Attacks
+Try to breach financial or write layers using the developer key. Watch Tillo's robust guard mechanism reject it.
+ +Sandbox Terminal Response
+ {playgroundStatus !== null && ( + = 200 && playgroundStatus < 300 ? 'success' : 'error'}`}> + HTTP {playgroundStatus} + + )} +
+ {JSON.stringify(playgroundResponse, null, 2)}
+
+ ) : (
+ Audit Firewall Log
+ {attackStatus !== null && ( + = 400 ? 'block' : 'breach'}`}> + {attackStatus === 401 || attackStatus === 403 ? 'BLOCKED - SECURE' : `STATUS ${attackStatus}`} + + )} +
+ {JSON.stringify(attackResponse, null, 2)}
+
+ API Reference Integration Guide
+How to use your Developer API keys to authenticate and query Tillo system details.
+1. System Architecture & Scope Segregation
++ The Tillo Developer API acts as a read-only integration layer designed to support external widgets, active status screens, and profile integrations. + Authorization is separated based on the owner of the API Key: +
+ +-
+
- Customer Key Scopes: Allows programmatic reading of the key owner's own orders and wallet balance. Perfect for building custom widgets or personal status trackers. +
- System Key Scopes: Allows canteen-wide catalog querying (stalls, product list, inventory levels) and overall statistics, but redacts specific customer transaction profiles. +
2. Authentication & Header Specs
+
+ All endpoints require you to supply your custom key inside the X-Developer-Key HTTP header.
+ Traditional JWT authorization headers (e.g., Authorization: Bearer ...) are not required and will be ignored when querying developer paths.
+
+{`curl -X GET \\
+ -H "X-Developer-Key: DEV-YOUR_API_KEY_HERE" \\
+ ${BACKEND_URL}/api/developer/v1/stalls`}
+
+ 3. Endpoint Directory (Read-Only)
+ +| HTTP Method | +Path | +Description / Usage | +Permissions / Scope | +
|---|---|---|---|
| GET | +/api/developer/v1/validate |
+ Verifies key health, active status, and returns key metadata. | +Key validated | +
| GET | +/api/developer/v1/stalls |
+ Lists active canteen stalls, descriptions, and operational status. | +Key validated | +
| GET | +/api/developer/v1/products |
+ Returns the active menu item catalog, categories, pricing, and current stock. | +Key validated | +
| GET | +/api/developer/v1/wallet |
+
+ Returns wallet balance. + • Default: Returns own balance (for Customer Key) or circulation stats (for System Key). + • Query Parameter: Pass ?mobileNumber=... or ?userId=... to check the wallet balance of any user in the system.
+ |
+ Any user balance, read-only | +
| GET | +/api/developer/v1/orders |
+
+ Retrieves active and completed order lists. + • Customer Key: Returns key owner's own orders. + • System Key: Lists system orders with financial elements (payout details) masked. + |
+ Owner scope, key validated | +
4. Core Rules & Security Shields
+🔒 Strict Mutation and Financial Block
++ To prevent unauthorized changes or leaks of financial parameters, developer API keys are bounded by strict policies: +
+-
+
- Read-Only Constraints: Standard operations like checking out, creating coupon codes, placing orders, or topping up balances are blocked. Mutation endpoints will return
401 Unauthorizedor403 Forbidden.
+ - Financial Isolation: General database tables containing financial audits, payment processor reference IDs, vendor billing settlements, and total daily canteen earnings are inaccessible to API keys. +
- Quota Limit: To prevent token spam, a hard limit of 3 API keys is enforced per account. Revoke an old key to create a new one. +
5. Error Responses Schema
+When query violations occur, the firewall returns standard JSON error bodies to simplify client parsing:
+
+{`{
+ "error": "Invalid or missing X-Developer-Key header"
+}`}
+
+
+{`{
+ "status": 403,
+ "error": "Forbidden",
+ "message": "Access Denied on restricted financial/mutation endpoint",
+ "path": "/api/wallet/topup"
+}`}
+
+ 6. Quick Integration JavaScript Snippet
+
+{`async function getCanteenMenu(apiKey) {
+ try {
+ const response = await fetch('${BACKEND_URL}/api/developer/v1/products', {
+ headers: {
+ 'X-Developer-Key': apiKey
+ }
+ });
+
+ if (!response.ok) {
+ const errorBody = await response.json();
+ throw new Error(errorBody.error || 'Failed to fetch');
+ }
+
+ const products = await response.json();
+ console.log('Active Products:', products);
+ return products;
+ } catch (error) {
+ console.error('API Error:', error.message);
+ }
+}`}
+
+