DOCSEARCHbyAlgolia
Submit Docs

Orkestra API Reference

website·Indexed 30 days ago

https://docs.orkestra.cc

API documentation for Orkestra, featuring detailed JSON schemas and endpoints for tenant management, user authentication, OAuth providers, and administrative controls. Includes references for managing client users, trusted devices, billing identities, and system audit events.

Tokens
143.5K
Snippets
612
Records
1.1K
Agent score
49%

What's inside Orkestra

  1. Overview of the NotificationSender interface

    The iface.NotificationSender interface provides a unified way for modules to deliver outbound messages without needing to manage transport, rendering, preferences, or suppressions. While designed for multi-channel support (SMS, push, webhook), currently only email is implemented. The primary consumer is the auth module for verification and password-reset emails.

  2. Overview of Orkestra operator-side architecture

    The operator-side surface of Orkestra consists of four primary areas:

    1. Deployment topology: A single binary architecture using one image and one process.
    2. Module configuration: Managed via environment variables, encrypted secrets, and per-environment profiles (e.g., sandbox vs. production).
    3. Integrations: Core integrations include SMTP for email and various OAuth providers. Vertical-specific forks may add payments or PDF rendering.
    4. Observability: Implemented through health checks, audit logs, and structured logging.

  3. SecurityEvent Schema Reference

    The SecurityEvent object represents a security-related event within the system. It contains details about the event type, the user involved, the network origin (IP and location), and the outcome of the event.
    {
  "description": "string",
  "deviceId": "string",
  "eventType": "string",
  "id": "string",
  "ipAddress": "string",
  "location": {
    "city": "string",
    "country": "string",
    "isp": "string",
    "latitude": 0,
    "longitude": 0,
    "timezone": "string"
  },
  "metadata": {},
  "riskScore": 0,
  "sessionId": "string",
  "severity": "string",
  "success": true,
  "timestamp": "2024-07-29T15:51:28.071Z",
  "userAgent": "string",
  "userUuid": "string"
}

  4. Understand the ListErasureRequestsOutputBody response schema

    The ListErasureRequestsOutputBody is the response object returned when listing erasure requests. It contains a required items array, where each element is an erasure request object containing details about the request's status, the user involved, and timing information.
    {
  "$schema": "https://example.com/schemas/ListErasureRequestsOutputBody.json",
  "items": [
    {
      "uuid": "string",
      "userUuid": "string",
      "status": "string",
      "requestedAt": "date-time",
      "mode": "string",
      "reason": "string",
      "resolutionNote": "string",
      "resolvedAt": "date-time",
      "resolvedBy": "string",
      "tenantId": "string"
    }
  ]
}

  5. Orkestra Platform Overview

    Orkestra is a 'core-only base' SaaS plumbing platform designed to provide the foundational infrastructure that most products rebuild. It ships with eight core modules: user, auth, authz, tenant, notification, navigation, logging, and compliance. Developers can build custom verticals (e.g., invoicing, payments, AI agents) on top of this base using the in-tree SDK contract and the Module seam, which can be toggled via /admin/modules.

  6. Understand Orkestra backend image and core modules

    Orkestra uses a core-only base architecture. There is a single backend image that includes eight always-loaded core modules: user, notification, tenant, authz, auth, navigation, logging, and compliance. The optionalModules catalog is empty by default. To add verticals like invoicing, payments, or AI, they must be added in-tree under internal/addons/<name>/ with a corresponding cmd/server/catalog_<name>.go and a custom image must be built.
    Latest Image: ghcr.io/orkestra-cc/orkestra/backend:latest
Pinned Image: ghcr.io/orkestra-cc/orkestra/backend:<sha>

  7. Understand the logging module architecture and boot process

    The logging module is a leaf in the dependency graph and is initialized last by the registry. This ensures all other modules have received their deps.Logger clones. These clones share a resolverBox atomic pointer via PerModuleLevelHandler, allowing log level changes to be applied retroactively across all modules.

    Boot Sequence:

    1. Service is seeded from environment variables (LOG_LEVEL and LOG_LEVEL_<MODULE>).
    2. Persisted configuration is loaded from MongoDB into an atomic.Pointer snapshot.
    3. main.go calls utils.SwapLevelResolver after InitAll to replace the static boot resolver with the live DB-backed resolver.
    4. Log reads are performed lock-free against the snapshot.

  8. Understand the TestEmailResponseBody schema

    The TestEmailResponseBody object represents the response received when testing an email delivery. It contains details about the message, the provider used, the sender profile, and the overall success status of the operation.
    {
  "$schema": "https://example.com/schemas/TestEmailResponseBody.json",
  "message": "string",
  "provider": "string",
  "sender": "string",
  "success": true
}

  9. Understand the ErrorDetail schema

    The ErrorDetail object is used to provide specific information about an error encountered during processing. It identifies exactly where the error occurred and provides a descriptive message.

    • location (string): The path to where the error occurred. Examples include JSON paths like body.items[3].tags or identifier paths like path.thing-id.
    • message (string): The descriptive text of the error message.
    • value: The actual value present at the specified location that caused the error.
    {
  "location": "string",
  "message": "string"
}

  10. Understand how permissions are resolved and cached

    Permissions are never stored in the JWT. A token only carries the user's global system role and organization memberships. Permissions are resolved per request and cached in Redis for 60 seconds. This architecture ensures that revocation (unbinding a role or disabling an account) is effectively instant, as the next request will trigger a fresh resolution regardless of the token's remaining TTL.

  11. Retrieve a single Tier-2 client user with tenant memberships

    Use the GET /v1/admin/client-users/:id endpoint to retrieve detailed information about a specific Tier-2 client user, including their tenant memberships. The :id path parameter must be the unique identifier of the client user.
    curl -X GET "https://<your-domain>/v1/admin/client-users/{id}"

  12. Retrieve tenant details as a platform administrator

    Platform administrators can retrieve information about a specific tenant by making a GET request to the /v1/admin/tenants/:tenantId endpoint. A successful request returns a 200 OK response.
    curl -X GET "https://<your-domain>/v1/admin/tenants/{tenantId}"