Skip to main content

Imported from docs/reference/api-endpoints.md in cloud-factory. Last synced: 2026-03-15

API Endpoints Reference

All services use JWT Bearer authentication unless marked as Public. Admin endpoints require admin or PLATFORM_ADMIN roles. Service-to-service endpoints use @ServiceOnly() guard.

Error responses follow RFC 7807 Problem Details format (application/problem+json).

Identity Service (port 3003)

Authentication (/auth)

MethodPathAuthDescription
POST/auth/registerPublicRegister a new user
POST/auth/loginPublicLogin with email/password
POST/auth/refreshPublicRefresh access token
POST/auth/logoutJWTLogout current user
GET/auth/oauth/googlePublicInitiate Google OAuth
GET/auth/oauth/google/callbackPublicGoogle OAuth callback
GET/auth/oauth/githubPublicInitiate GitHub OAuth
GET/auth/oauth/github/callbackPublicGitHub OAuth callback
GET/auth/oauth/microsoftPublicInitiate Microsoft OAuth
GET/auth/oauth/microsoft/callbackPublicMicrosoft OAuth callback

Rate limits apply on all auth endpoints. OAuth callbacks set httpOnly cookies and redirect to frontend.

Users (/users)

MethodPathAuthDescription
GET/users/meJWTGet current user profile
PATCH/users/meJWTUpdate own profile
POST/users/me/change-passwordJWTChange own password
GET/usersAdminList all users (paginated, filterable)
GET/users/:idAdminGet user by ID
PUT/users/:idAdminUpdate a user (admin)
POST/users/:id/deactivateAdminSuspend a user
POST/users/:id/reactivateAdminReactivate a user

Tenants (/tenants)

MethodPathAuthDescription
POST/tenantsAdminCreate a new tenant
GET/tenantsAdminList all tenants (optional type filter)
GET/tenants/by-name/:nameAdminGet tenant by name
GET/tenants/:idAdminGet tenant by ID
PATCH/tenants/:idAdminUpdate a tenant
DELETE/tenants/:idAdminDelete a tenant
GET/tenants/:id/user-countAdminGet user count for tenant
GET/tenants/:id/settingsAdminGet tenant settings
PATCH/tenants/:id/settingsAdminUpdate tenant settings (partial)
POST/tenants/:id/invitesAdminCreate an invite
GET/tenants/:id/invitesAdminList invites for tenant
DELETE/tenants/:id/invites/:inviteIdAdminRevoke an invite
GET/tenants/invites/validate/:tokenPublicValidate invite token

Roles (/roles)

MethodPathAuthDescription
GET/rolesAdminList all role definitions
GET/roles/:idAdminGet role by ID
POST/rolesAdminCreate a role
PUT/roles/:idAdminUpdate a role
DELETE/roles/:idAdminDelete a role (non-system only)
GET/roles/users/:userIdAdminGet roles for a user (with details)
POST/roles/users/:userId/assignAdminAssign roles to user
POST/roles/users/:userId/removeAdminRemove roles from user

API Keys (/api-keys)

MethodPathAuthDescription
GET/api-keysJWTList API keys (optional userId filter)
POST/api-keysJWTCreate a new API key
DELETE/api-keys/:idJWTDelete an API key

Audit Logs (/audit-logs)

MethodPathAuthDescription
GET/audit-logsAdmin/SecurityList audit logs (paginated, filterable)
POST/audit-logsService-onlyCreate audit log entry

GDPR (/users/me)

MethodPathAuthDescription
GET/users/me/exportJWTExport personal data (Art. 20)
DELETE/users/me/eraseJWTRequest data erasure (Art. 17)
GET/users/me/consentJWTGet current consent status
GET/users/me/consent/historyJWTGet consent change history
POST/users/me/consentJWTRecord/update consent

Partner API (/api/partner)

MethodPathAuthDescription
POST/api/partner/clientsAdmin/PartnerCreate OAuth2 client
GET/api/partner/clientsAdmin/PartnerList OAuth2 clients
POST/api/partner/clients/:id/revokeAdmin/PartnerRevoke client
DELETE/api/partner/clients/:idAdmin/PartnerDelete client
POST/api/partner/oauth/tokenPublicClient credentials grant

Service Auth (/auth/service)

MethodPathAuthDescription
POST/auth/service/tokenService secretIssue service-to-service token

Health

MethodPathAuthDescription
GET/healthPublicHealth check (K8s probes)

Product Service (port 3001)

Products (/products)

MethodPathAuthDescription
POST/productsAdmin/Product ManagerCreate product
GET/productsPublicList products (paginated, filterable)
GET/products/searchPublicFull-text search with filters
GET/products/search/suggestPublicAutocomplete suggestions
GET/products/search/categoriesPublicList all categories
GET/products/:idPublicGet product by ID
PUT/products/:idAdmin/Product ManagerUpdate product
DELETE/products/:idAdminDelete product

Pricing Plans (/pricing-plans)

MethodPathAuthDescription
GET/pricing-plansPublicList products (legacy endpoint)

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Order Service (port 3002)

Orders (/orders)

MethodPathAuthDescription
POST/ordersJWTCreate order and submit for payment
GET/ordersJWTList orders (paginated, filterable)
GET/orders/analyticsJWTGet order analytics/metrics
GET/orders/statsJWTGet order statistics
GET/orders/:idJWTGet order by ID
POST/orders/:id/submitJWTSubmit order for payment
POST/orders/:id/confirm-paymentJWTConfirm payment
POST/orders/:id/revert-paymentJWTRevert payment to pending
POST/orders/:id/start-provisioningJWTStart provisioning pipeline
POST/orders/:id/cancelJWTCancel an order
GET/orders/:id/items/:itemId/deliveryJWTGet delivery info for item
POST/orders/:id/items/:itemId/deliverJWTSend/resend delivery email

Idempotency-Key header supported on: create, submit, confirm-payment, cancel.

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Provisioning Service (port 3004)

Provisioning (/provisioning)

MethodPathAuthDescription
POST/provisioning/requestsJWTCreate provisioning request
GET/provisioning/requestsJWTList requests (paginated)
GET/provisioning/requests/:idJWTGet request by ID
GET/provisioning/requests/order/:orderIdJWTGet requests by order ID
GET/provisioning/requests/:id/metricsJWTGet real-time service metrics
GET/provisioning/requests/:id/auditJWTGet audit trail
POST/provisioning/requests/:id/startService-onlyStart provisioning
POST/provisioning/requests/:id/advanceService-onlyAdvance to next step
POST/provisioning/requests/:id/failService-onlyMark as failed
POST/provisioning/requests/:id/suspendJWTSuspend service
POST/provisioning/requests/:id/reactivateJWTReactivate service
PATCH/provisioning/requests/:id/manual-completeJWTComplete manual provisioning
POST/provisioning/requests/:id/retryJWTRetry failed request
DELETE/provisioning/requests/:idJWTDeprovision service
GET/provisioning/statsJWTGet provisioning statistics
GET/provisioning/instancesJWTList active service instances
GET/provisioning/worker-statusJWTGet worker status
GET/provisioning/providers/healthJWTCheck cloud provider health

DNS (/dns)

MethodPathAuthDescription
GET/dns/zonesJWTList DNS zones
POST/dns/zonesJWTCreate zone
GET/dns/zones/:zoneIdJWTGet zone details
PATCH/dns/zones/:zoneIdJWTUpdate zone settings
DELETE/dns/zones/:zoneIdJWTDelete zone
POST/dns/zones/:zoneId/verifyJWTVerify NS delegation
GET/dns/zones/:zoneId/exportJWTExport zone (BIND format)
GET/dns/zones/:zoneId/recordsJWTList records
POST/dns/zones/:zoneId/recordsJWTCreate record
POST/dns/zones/:zoneId/records/bulkJWTBulk record operations
GET/dns/zones/:zoneId/records/:recordIdJWTGet record
PATCH/dns/zones/:zoneId/records/:recordIdJWTUpdate record
DELETE/dns/zones/:zoneId/records/:recordIdJWTDelete record
POST/dns/rdnsJWTSet reverse DNS
GET/dns/rdns/:ipJWTGet reverse DNS
DELETE/dns/rdns/:ipJWTRemove reverse DNS
GET/dns/admin/zonesAdminList all zones (cross-tenant)
GET/dns/admin/statsAdminDNS statistics
GET/dns/admin/templatesAdminList zone templates
POST/dns/admin/templatesAdminCreate zone template
DELETE/dns/admin/templates/:templateIdAdminDelete zone template

Clusters, Approvals, Quotas, Webhooks, Analytics

Additional controller endpoints exist for cluster management, approval workflows, quota management, webhook integrations, and provisioning analytics.

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Billing Integration Service (port 3005)

Invoices (/invoices)

MethodPathAuthDescription
POST/invoicesJWTCreate invoice
GET/invoicesJWTList invoices (filterable)
GET/invoices/overdue/listJWTList overdue invoices
GET/invoices/statsJWTGet billing statistics
GET/invoices/:idJWTGet invoice by ID
GET/invoices/:id/pdfJWTDownload invoice PDF
GET/invoices/number/:invoiceNumberJWTGet invoice by number
POST/invoices/:id/sendJWTSend invoice to customer
POST/invoices/:id/voidService-onlyVoid an invoice

Subscriptions (/subscriptions)

MethodPathAuthDescription
POST/subscriptionsJWTCreate subscription
GET/subscriptionsJWTList subscriptions (filterable)
GET/subscriptions/:idJWTGet subscription by ID
POST/subscriptions/:id/cancelJWTCancel subscription
POST/subscriptions/:id/pauseJWTPause subscription
POST/subscriptions/:id/resumeJWTResume subscription
POST/subscriptions/:id/upgradeJWTUpgrade/downgrade
GET/subscriptions/customer/:customerIdJWTGet active subscriptions for customer

Payments (/payments)

MethodPathAuthDescription
GET/paymentsJWTList payment transactions
POST/payments/processService-onlyProcess payment for invoice
POST/payments/create-intentJWTCreate Stripe payment intent
GET/payments/methodsJWTList payment methods
POST/payments/methodsJWTAdd payment method
DELETE/payments/methods/:idJWTRemove payment method
PUT/payments/methods/:id/defaultJWTSet default payment method

Usage (/usage)

MethodPathAuthDescription
POST/usage/recordJWTRecord usage
POST/usage/record-batchJWTBatch record usage
GET/usageJWTList usage records
GET/usage/summaryJWTGet usage summary for period
GET/usage/customer/:customerIdJWTGet customer usage
GET/usage/unbilledJWTGet unbilled usage records

Rating (/rating)

MethodPathAuthDescription
POST/rating/pricing-rulesJWTCreate pricing rule
PUT/rating/pricing-rules/:idJWTUpdate pricing rule
GET/rating/pricing-rules/product/:productIdJWTGet rules for product
POST/rating/calculateJWTCalculate rated usage

Refunds (/refunds)

MethodPathAuthDescription
POST/refundsJWTCreate refund request
POST/refunds/:id/processJWTProcess refund via Stripe
POST/refunds/disputeJWTHandle chargeback dispute
GET/refundsJWTList refunds (filterable)
GET/refunds/:idJWTGet refund by ID

Webhooks, Analytics, Scheduler

Additional endpoints for Stripe webhooks, billing analytics, and scheduler controls.

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Notification Service (port 3006)

Notifications (/notifications)

MethodPathAuthDescription
POST/notifications/sendService-onlySend notification
GET/notificationsJWTList notifications (paginated)
GET/notifications/unreadJWTGet unread count
PATCH/notifications/:id/readJWTMark as read
PATCH/notifications/read-allJWTMark all as read
DELETE/notifications/:idJWTDelete notification

Preferences (/notifications/preferences)

MethodPathAuthDescription
GET/notifications/preferencesJWTList preferences
PUT/notifications/preferences/:eventTypeJWTUpdate preference

Templates (/templates)

MethodPathAuthDescription
GET/templatesJWTList email templates
GET/templates/branding/currentJWTGet tenant branding
PUT/templates/branding/currentJWTUpdate tenant branding
GET/templates/:idJWTGet template
PUT/templates/:idJWTUpdate template
POST/templates/previewJWTRender template preview
POST/templates/:id/send-testJWTSend test email

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Support Service (port 3007)

Tickets (/tickets)

MethodPathAuthDescription
POST/ticketsJWTCreate support ticket
GET/ticketsJWTList tickets (paginated, filterable)
GET/tickets/statsJWTGet ticket statistics
GET/tickets/:idJWTGet ticket with comments
PATCH/tickets/:idAdmin/AgentUpdate ticket
PATCH/tickets/:id/assignAdmin/AgentAssign to agent
PATCH/tickets/:id/closeAdmin/AgentClose ticket
PATCH/tickets/:id/reopenAdmin/AgentReopen ticket

Comments (/tickets/:ticketId/comments)

MethodPathAuthDescription
POST/tickets/:ticketId/commentsJWTAdd comment
GET/tickets/:ticketId/commentsJWTList comments

Analytics, Health

Additional endpoints for support analytics and health checks.

Reporting Service (port 3008)

Dashboard (/dashboard)

MethodPathAuthDescription
GET/dashboardJWTGet dashboard overview metrics

Revenue (/revenue)

Revenue analytics endpoints.

Customer Health (/customer-health)

Customer health score endpoints.

Provisioning Analytics (/provisioning-analytics)

Provisioning performance analytics.

Infrastructure (/infrastructure)

Infrastructure monitoring endpoints.

FOCUS Cost (/focus)

FOCUS 1.0 cost data endpoints.

Exports (/exports)

Report export endpoints.

Schedules (/schedules)

Scheduled report management.

Health

MethodPathAuthDescription
GET/healthPublicHealth check

Common Headers

HeaderRequiredDescription
AuthorizationYes (unless Public)Bearer <jwt_token>
X-Correlation-IdNoRequest tracing (auto-generated if absent)
Idempotency-KeyNoUUID v4 for idempotent operations
X-Tenant-IdNoOverride effective tenant (platform admins only)

Common Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100-200)
sortBystringSort field
sortOrderstringASC or DESC
searchstringFull-text search query
Previous
Cloud Factory Platform Documentation
Next
Error Codes Reference