Developers
This guide covers everything you need to integrate with or build on top of the Powoflow platform — API access, authentication, real-time events, and the integration framework.
API Documentation
Powoflow provides interactive Swagger UI documentation for both APIs.
User API
The User API is the primary API for all end-user operations — assets, work orders, inventory, alarms, sensors, and more.
| Environment | Swagger UI |
|---|---|
| Development | https://api.dev1.powoflow.com/docs |
| Production | https://api.powoflow.com/docs |
Management API
The Management API is used for platform administration — tenant management, user provisioning, billing, and system configuration.
| Environment | Swagger UI |
|---|---|
| Development | https://mgmt.dev1.powoflow.com/docs |
| Production | https://mgmt.powoflow.com/docs |
Use the Swagger UI to explore endpoints, view request/response schemas, and test API calls interactively. You can authorize with your JWT token directly in the UI.
Authentication
Powoflow uses Auth0 OAuth2 with the PKCE (Proof Key for Code Exchange) flow for secure authentication.
Auth0 Domains
| Environment | Auth0 Domain |
|---|---|
| Development | kiowa-dev1.us.auth0.com |
| Production | kiowa-prod.us.auth0.com |
Authentication Flow
- Your application initiates the Auth0 PKCE flow with the appropriate domain
- The user authenticates via the Auth0 Universal Login page
- Auth0 returns an authorization code
- Your application exchanges the code for an access token (JWT)
- Include the JWT in all API requests via the
Authorizationheader
API Request Format
Authorization: Bearer <access_token>
JWT Token Claims
The access token contains the following claims relevant to Powoflow:
| Claim | Description |
|---|---|
tenant_id | The user's organization identifier |
roles | Array of assigned roles (e.g., ["admin", "member"]) |
platform_admin | Boolean flag for platform-level administrators |
sub | Auth0 user ID |
exp | Token expiration timestamp |
Tokens expire after the configured TTL (typically 1 hour). Use refresh tokens to obtain new access tokens without requiring the user to re-authenticate.
Client Libraries
| Platform | Library |
|---|---|
| Flutter (mobile) | auth0_flutter |
| Next.js (web) | @auth0/nextjs-auth0 v4 |
API Overview
The Powoflow User API is organized into the following endpoint groups. Endpoint counts reflect the total number of unique operations available.
| Group | Endpoints | Description |
|---|---|---|
| Resources | 37 | CRUD, hierarchy, items, links, external IDs |
| Work Orders | 49 | CRUD, tasks, assignments, time, costs, comments, signatures, PM schedules |
| Inventory | 26 | Parts, stock, mutations, kits, serials, valuation |
| Integrations | 23 | Vendors, geo-data, geo-alerts, subscriptions |
| Location & Telemetry | 19 | GNSS positions, sensor data, fleet locations |
| User & Account | 19 | Profile, settings, team, personalization |
| Video & Camera | 17 | Streams, recordings, screenshots, ONVIF, PTZ |
| Alarms | 15 | CRUD, state transitions, ISA 18.2 |
| Checklists | 12 | Templates, tasks, reorder |
| Meters | 8 | CRUD, readings |
| AI Assistant | 1 | Multi-turn chat with tool calling |
Resources (37 endpoints)
Core asset and resource management:
- Create, read, update, delete resources
- Hierarchy management (parent/child relationships)
- Items (sub-records attached to resources)
- Links (relationships between resources: parent, child, related, depends_on, etc.)
- External ID mapping (for ERP/CMMS bidirectional sync)
- Bulk operations
Work Orders (49 endpoints)
Full maintenance management lifecycle:
- Work order CRUD and status transitions
- Task management (8 task types with validation)
- Assignments (assign/unassign technicians)
- Time tracking (labor hour entries)
- Cost tracking (labor, material, equipment)
- Comments (threaded discussion)
- Signatures (digital sign-off capture)
- Maintenance requests (simplified submission)
- PM Schedules (recurring work order generation)
- Checklist templates (reusable task lists)
Inventory (26 endpoints)
Spare parts and stock management:
- Parts catalog CRUD
- Stock operations (receive, issue, transfer, adjust, return)
- Transaction history and audit trail
- Part kits (grouped assemblies)
- Serialized inventory (individual serial number tracking)
- Stock valuation (weighted average cost)
Alarms (15 endpoints)
ISA 18.2-compliant alarm management:
- Alarm configuration and thresholds
- State transitions: triggered, acknowledged, shelved, suppressed, cleared
- Alarm history and statistics
- Priority and severity classification
The full OpenAPI specification is available at the Swagger UI URLs listed above. Use the spec to generate client libraries in any language.
WebSocket API
Powoflow provides a WebSocket API for real-time updates. Use this to build live dashboards, real-time monitoring, and instant notifications.
Connection
wss://ws.dev1.powoflow.com?token={accessToken}
Replace {accessToken} with a valid JWT access token. The WebSocket server validates the token on connection and associates the session with the user's tenant.
Subscribe to Resource Updates
Send a subscribe message to receive real-time updates for a specific resource:
{
"action": "subscribe",
"resourceId": "res_01HQ..."
}
Subscribe to Activity Feed
Receive all activity events for your tenant:
{
"action": "subscribe_activity"
}
Real-Time Event Types
Once subscribed, you'll receive events as JSON messages:
| Event Type | Description | Payload |
|---|---|---|
location_update | Device GPS position changed | lat, lng, speed, heading, timestamp |
sensor_reading | New sensor value received | sensorId, value, unit, timestamp |
camera_event | Camera event detected | cameraId, eventType, timestamp |
status_change | Resource status changed | resourceId, oldStatus, newStatus |
alarm_triggered | Alarm condition met | alarmId, severity, resourceId |
alarm_cleared | Alarm condition resolved | alarmId, resourceId |
work_order_update | Work order changed | workOrderId, field, oldValue, newValue |
activity | General activity event | type, userId, resourceId, details |
Subscribe only to the resources you need. Each subscription creates a filtered stream — subscribing to too many resources increases message volume and bandwidth usage.
EventBridge Events
Powoflow publishes events to AWS EventBridge for integration developers who need to react to platform events asynchronously.
Event Bus
Events are published to the Powoflow platform event bus. Integration developers can create EventBridge rules to route events to their own targets (Lambda, SQS, SNS, etc.).
Event Types
| Event Type | Description |
|---|---|
resource.created | A new resource was created |
resource.updated | A resource was modified |
resource.deleted | A resource was deleted |
sensor_reading | A new sensor reading was received |
location_update | A device reported a new GPS position |
camera_motion | Motion detected on a camera |
device_status | Device went online/offline |
integration_synced | An integration completed a sync cycle |
alarm.triggered | An alarm condition was met |
alarm.cleared | An alarm condition was resolved |
alarm.acknowledged | An alarm was acknowledged by a user |
work_order.created | A new work order was created |
work_order.status_changed | A work order status transitioned |
work_order.completed | A work order was completed |
inventory.stock_changed | Inventory stock level changed |
inventory.serial_status_changed | A serialized part changed status |
checklist.completed | A checklist was fully completed |
user.invited | A new user was invited to the tenant |
EventBridge events include the full resource payload and metadata (tenant ID, user ID, timestamp). See the EventBridge console for detailed schema definitions.
Integration Framework
Build custom integrations using Powoflow's integration pipeline.
Webhook Handler
Receive real-time data from external systems via webhooks.
Endpoint:
POST /integrations/{vendorId}/webhook
5-Step Pipeline
Every inbound integration (webhook or poll) passes through a standardized pipeline:
| Step | Description |
|---|---|
| 1. Authenticate | Validate the request source (API key, HMAC signature, IP allowlist) |
| 2. Parse | Extract structured data from the raw payload |
| 3. Validate | Verify data integrity and required fields |
| 4. Sync | Create or update resources in Powoflow (idempotent) |
| 5. Telemetry | Record sensor readings, location updates, or status changes |
Adapter Base Classes
Powoflow provides base classes for building custom adapters:
| Base Class | Use Case |
|---|---|
base_adapter.py | General-purpose poll adapter |
base_geo_adapter.py | Geo-data feed adapter (inherits standard geo-data processing) |
base_webhook_handler.py | Real-time webhook receiver |
Sync Engine
The sync engine handles create/update operations with built-in safety:
- Idempotent creates — duplicate data is detected and skipped using external ID mapping
- Conflict resolution — configurable strategy for handling concurrent updates (last-write-wins, manual review)
- External ID mapping — each synced record maintains a mapping between the Powoflow resource ID and the external system's ID for bidirectional tracking
When building custom adapters, always implement idempotency. The sync engine supports this via external ID lookups — check for an existing mapping before creating a new resource.
SDKs & Libraries
Current Status
There is no official Powoflow SDK at this time. The recommended approach is to use the OpenAPI specification to generate client libraries in your language of choice.
Generating a Client
- Download the OpenAPI spec from the Swagger UI (
/docsendpoint) - Use a code generator such as OpenAPI Generator or Swagger Codegen
- Generate a client in your preferred language (Python, TypeScript, Java, Go, C#, etc.)
# Example: generate a TypeScript client
openapi-generator-cli generate \
-i https://api.powoflow.com/docs/openapi.json \
-g typescript-fetch \
-o ./powoflow-client
Authentication Libraries
| Platform | Library | Usage |
|---|---|---|
| Flutter | auth0_flutter | Mobile app authentication with PKCE |
| Next.js | @auth0/nextjs-auth0 v4 | Server-side and client-side authentication |
| Generic | Any OAuth2/OIDC library | Use the Auth0 domain and PKCE flow |
When generating API clients, configure the base URL to point to your environment (api.dev1.powoflow.com for development, api.powoflow.com for production) and set up an interceptor to attach the Authorization: Bearer header to all requests.