Integrations and troubleshooting
Installation overview · Install and upgrade
Integration credentials
The API generates AppSettings:ApiKey in its machine-specific settings file on
first startup if no key exists. Existing keys, including older formats, remain
valid after an upgrade. Treat the key as a password: restrict settings and
backups, share it only with services that need it, and keep it out of logs,
tickets, source control and handover notes.
The API accepts one integration key. To rotate it, schedule a maintenance
window, stop the integrations, generate a new SK- key from 16 cryptographically
random bytes, update the API and every integration's protected settings, then
restart and verify them. There is no overlap between old and new keys.
Maximo and maintenance-system integrations
Integrations are installed separately from the four core services. The Maximo
integration uses OTBackup:ApiKey for OT Backup and a separate Maximo:ApiKey
for Maximo. Configure both endpoints and credentials in protected settings,
then verify calls to both systems. The OT Backup API certificate must be
trusted; do not disable certificate validation.
For the Maintenance System Integration, see its configuration, Maximo provider and operations pages. Verify the intended site, filters and synchronization settings with the system owner.
Troubleshooting
| Symptom | Check |
|---|---|
| API does not start | Database connections, SQL and migration permissions, certificate settings and API log. |
| UI cannot reach API | API address and ports, Cors:UI, TLS trust and API log. |
| External sign-in is unavailable | API availability, provider settings, callback URLs and API-only client secret. |
| Queue or TEE cannot connect | Shared actor settings, addresses, ports and firewall rules. |
| Integration gets an authentication error | Check its OT Backup key matches the API key; check the separate provider credential for remote-system errors. |
| Key changed after an upgrade | Restore the saved API machine settings, then verify the key in every integration and restart the affected services. |
| Settings are ignored | Check the override file name and configuration order. |
HTTPS fails for localhost |
Use a DNS name covered by the certificate or a trusted certificate valid for that name. |