Integrations
Turqoa connects to your existing port infrastructure through a modular integration layer. Each integration follows a standardized adapter pattern, ensuring consistent authentication, error handling, and data flow regardless of the external system.
Integration Architecture
Turqoa uses an adapter-based integration model. Each external system communicates through a dedicated adapter that normalizes data into Turqoa's internal event schema. Adapters run as independent microservices, enabling isolated scaling, deployment, and failure recovery.
Turqoa Core
→ Event Bus (Kafka)
→ Decision Engine
→ Data Store (PostgreSQL)
│
▼
Integration Adapter Layer
│ │ │
▼ ▼ ▼
TOS Cameras SSO
(N4, (ONVIF, (SAML,
TOPS) RTSP) OIDC)
Supported Systems
| Category | System | Protocol | Status |
|---|---|---|---|
| Terminal Operating System | Navis N4 | REST API / Web Services | GA |
| Terminal Operating System | TOPS Expert | SOAP / XML | GA |
| Terminal Operating System | Tideworks | REST API | Beta |
| Camera Systems | ONVIF-compliant cameras | ONVIF / RTSP | GA |
| Camera Systems | Axis Communications | VAPIX + ONVIF | GA |
| Camera Systems | Hikvision / Dahua | ISAPI + ONVIF | GA |
| Identity Providers | Azure AD / Entra ID | SAML 2.0 / OIDC | GA |
| Identity Providers | Okta | SAML 2.0 / OIDC | GA |
| Identity Providers | On-premise ADFS | SAML 2.0 | GA |
Authentication Methods
Turqoa adapters support multiple authentication mechanisms depending on the target system:
- API Key --- Static keys stored in Turqoa's encrypted credential vault. Used for TOS REST APIs.
- OAuth 2.0 Client Credentials --- Machine-to-machine authentication for cloud-hosted services.
- Certificate-based (mTLS) --- Mutual TLS for high-security integrations. Required for some TOS deployments.
- SAML / OIDC --- Federated identity for operator authentication via SSO providers.
All credentials are stored encrypted at rest using AES-256 and are never logged or exposed in API responses.
Data Flow Patterns
Inbound (External to Turqoa)
External systems push or are polled for data that feeds into Turqoa's event pipeline:
- Webhook push --- The external system sends events to a Turqoa-hosted endpoint (preferred).
- Polling --- Turqoa periodically queries the external system for new data (fallback when webhooks are unavailable).
- Stream ingestion --- Continuous data streams such as RTSP video feeds from cameras.
Outbound (Turqoa to External)
Turqoa publishes decisions and events back to external systems:
- Decision callbacks --- Gate decisions are sent to the TOS to update appointment and container status.
- Event notifications --- Security events are forwarded to SIEM or alerting systems via webhook.
- Audit exports --- Scheduled or on-demand export of audit data to external compliance systems.
Next Steps
- TOS Integration --- Connect Turqoa to your Terminal Operating System
- Camera Integration --- Set up camera feeds for gate and security zones
- SSO Integration --- Configure single sign-on for operator authentication