API Reference

All Cloud Backend endpoints use the prefix /api/v1. This page documents the route groups and their purposes. For per-endpoint request/response details, refer to the source handlers in Backend/internal/domain/<package>/handler.go.

Route groups

Group	Prefix	Auth required	Notes
Auth	/api/v1/auth/*	No (login endpoints)	Some sub-routes require JWT
Me	/api/v1/me	JWT	Current user profile, features, permissions
Tenants	/api/v1/tenants/*	JWT + tenant:manage	Tenant settings accessible via /settings in UI
Users	/api/v1/users/*	JWT + users:*	User management
Assets	/api/v1/assets/*	JWT + assets:*	CMDB asset registry
Sites	/api/v1/sites/*	JWT + sites:*	Physical site registry
Zones / VLANs	/api/v1/zones/*, /api/v1/vlans/*	JWT + assets:*	Network hierarchy
Incidents	/api/v1/incidents/*	JWT + incidents:*	ITSM incident management
Problems	/api/v1/problems/*	JWT + problems:*	ITSM problem management
Changes	/api/v1/changes/*	JWT + changes:*	ITSM change management
Releases	/api/v1/releases/*	JWT + releases:*	Release management
PIR	/api/v1/pir/*	JWT + incidents:*	Post-incident reviews
Service Requests	/api/v1/service-requests/*	JWT + service-requests:*	Service catalog
Maintenance	/api/v1/maintenance/*	JWT + maintenance:*	Maintenance windows
Knowledge	/api/v1/knowledge/*	JWT + knowledge:*	Knowledge base articles
Diagrams	/api/v1/diagrams/*	JWT + diagrams:*	Network diagrams
Vulnerabilities	/api/v1/vulnerabilities/*	JWT + vulnerabilities:*	CVE records and remediation
Security	/api/v1/security/*	JWT + security:*	SOC alerts, investigations (optional module)
Compliance	/api/v1/compliance/*	JWT + compliance:*	Frameworks and controls (optional module)
Playbooks	/api/v1/playbooks/*	JWT + security:manage	Response automation (optional module)
VPN	/api/v1/vpn/*	JWT + vpn:*	VPN gateways and sessions (optional module)
Backup	/api/v1/backup/*	JWT + backup:*	Backup repos and jobs (optional module)
Vendors	/api/v1/vendors/*	JWT + vendors:*	Vendor registry
Notifications	/api/v1/notifications/*	JWT	In-app notification badge
Settings	/api/v1/settings/*	JWT + settings:*	Tenant-level configuration
Devices	/api/v1/devices/*	Provisioning key / JWT	Edge device management
Commands	/api/v1/commands	Device key	Command polling for Edge
Snaps	/api/v1/snaps/*	Device key / JWT	OTA snap update metadata
Admin	/api/v1/admin/*	JWT + platform email domain	Cross-tenant console (optional)
Integrations	/api/v1/integrations/*	JWT (setup) / webhook token (ingest)	Webhook ingest configuration
Public	/public/*	None	Vendor assessment portal
Internal	/internal/license/refresh	HMAC signature	Management → Cloud webhook
WebSocket	/api/ws/security, /api/ws/vpn	JWT query param	Real-time subscriptions

Auth endpoints detail

Endpoint	Method	Notes
/api/v1/auth/login	POST	Email + password login
/api/v1/auth/register	POST	New tenant + user registration
/api/v1/auth/logout	POST	Invalidate refresh token
/api/v1/auth/refresh	POST	Issue new access token from refresh cookie
/api/v1/auth/check-method	POST	Determine login method for email (password vs SSO)
/api/v1/auth/mfa/verify	POST	TOTP verification step
/api/v1/auth/microsoft/login	GET	Initiate Entra ID OIDC flow
/api/v1/auth/microsoft/callback	GET	OIDC callback (must match Entra redirect URI)
/api/v1/auth/invite/:token	GET/POST	User invitation flow
/api/v1/auth/password-reset	POST	Request password reset

Response conventions

• Success: 200 OK with JSON body (or 201 Created for resource creation, 204 No Content for deletions)
• Validation error: 400 Bad Request with { error: "..." } or field-level errors
• Unauthorized: 401 Unauthorized
• Forbidden (permission missing): 403 Forbidden
• Not found: 404 Not Found
• Conflict: 409 Conflict (e.g. duplicate unique value)
• Server error: 500 Internal Server Error (logged with zerolog + OpenTelemetry)

Route registration source

All routes are registered in Backend/internal/app/register_*.go. To find the handler for a specific route:

1. Open the corresponding register_*.go file
2. Find the route path and HTTP method
3. Follow the handler reference to internal/domain/<package>/handler.go