logiccloud orchestrate team
Overview
logiccloud orchestrate API 2.105.2
Section titled “logiccloud orchestrate API 2.105.2”Overview
logiccloud orchestrate REST API for managing edge device fleets and workload deployments. logiccloud orchestrate implements the Workload Fleet Manager (WFM) role of the Margo specification.
Authentication
All API endpoints require authentication via Bearer token or API key.
Bearer Token
Authorization: Bearer <jwt_token>API Key
X-API-Key: <api_key>Tenant scoping
The API is multi-tenant. Every endpoint acts in exactly one organization (tenant) unless it is marked as a global operation.
Selecting the tenant
Send the x-organization-id header with the UUID of the organization. This header is the contract for API clients. It selects the tenant and grants nothing: the server still checks that you may act there. A malformed value returns 400. If you send no header, the server uses your open tenant switch, or else your primary organization. A route that names an organization in its path or body uses that organization, and a conflicting header is rejected with 403.
The web UI uses organization slugs in its page URLs. That is a web UI concept. The API only accepts the organization id. The x-organization-source header grants nothing: a forged value never bypasses any check.
Global operations
Some endpoints are not scoped to one tenant and need no x-organization-id: the /api/v1/tenant/* context and switch endpoints, the platform-level organization lifecycle and record endpoints under /api/v1/organizations (superadmin), platform-wide activity and reporting endpoints under /api/v1/activity, and authentication event ingestion. All other endpoints are tenant-scoped.
Home tenants and tenant switches
A home tenant is any tenant you are a member of. You act in a home tenant without a switch. POST /api/v1/tenant/switch to a home tenant opens no switch, ends any open switch and returns 204.
A superadmin, or a user with the SUPPORT system role, who acts in a tenant they are not a member of needs an open tenant switch. Open one with POST /api/v1/tenant/switch and a reason (3-500 characters after trimming, else 400). The response is 201. A switch applies to the user’s own requests only.
Switch lifetime
A switch lasts 8 hours by default. You can choose an expiresAt up to 72 hours from now when you open it, and you can extend it with PATCH /api/v1/tenant/switch (new expiry at most 72 hours from now). A switch ends at its expiry (checked every 5 minutes), with DELETE /api/v1/tenant/switch, or when the user logs out of the web UI. CLI and SDK clients do not log out through the web UI, so the 8 hour default is their backstop: end the switch explicitly.
Tenant rejections (403)
- No open switch: a superadmin or SUPPORT user targets a tenant they are not a member of. The body is
{"statusCode": 403, "error": "Forbidden", "code": "TENANT_SWITCH_REQUIRED", "message": "A tenant switch is required to act in this organization", "organizationId": "<tenant>"}. Open a switch, then repeat the request. Schema:TenantSwitchRequiredErrorDto. Global operations never return it. - Not a member: a user without a system role targets a tenant they are not a member of. The body is the standard error body with the message
Not a member of this organization. - The organization does not exist, or is inactive: 403 with the message
Organization not foundorOrganization is inactive. - The
x-organization-idheader and the organization in the path differ: 403. - Insufficient permission in the tenant: 403.
API keys
An API key is fixed to the organization it was issued for. It never uses a tenant switch, not even one of the user who created it. A header or path naming another organization returns 403 (API key not authorized for this organization). Every /api/v1/tenant/switch* endpoint, and the other tenant context endpoints under /api/v1/tenant, returns 403 for an API key.
Rate Limiting
- Default: 100 requests per minute
- Burst: 20 requests per second
Pagination
List endpoints support pagination via page and pageSize query parameters:
page: Page number (default: 1)pageSize: Items per page (default: 20, max: 100)
Filtering
Most list endpoints support filtering via query parameters specific to the resource.
Error Responses
Errors use the standard NestJS body: {"statusCode": <status>, "message": <text, or a list of texts for validation errors>, "error": "<status name>"}. Some errors add a machine-readable code and context fields, for example TENANT_SWITCH_REQUIRED above. The body does not follow RFC 7807 Problem Details.
Authentication
Section titled “Authentication”bearer
Section titled “bearer”JWT authentication token
Security scheme type: http
Bearer format: JWT
api-key
Section titled “api-key”API key for service-to-service communication
Security scheme type: apiKey
Header parameter name: X-API-Key