Base URL

All requests use versioned HTTPS endpoints. Use sandbox during onboarding; production is planned for approved partners only.

Endpoint categories

The future API surface is organised around operational domains across Ecovira’s ecosystem.

Example endpoint

Retrieve a project by identifier. Response fields are designed for stable integration and source attribution.

GET /v1/projects/eco_prj_1048
Authorization: Bearer eco_sk_sandbox_xxxxxxxxx
Accept: application/json

{
  "project_id": "eco_prj_1048",
  "status": "in_progress",
  "source": "workvira_nexus",
  "updated_at": "2026-05-25T04:00:00Z"
}

Response format

Responses are JSON with consistent conventions across the planned API surface.

• JSON — all successful and error payloads use application/json
• Stable identifiers — prefixed IDs (e.g. eco_prj_*, evt_*) for long-lived references
• Status fields — operational states aligned with coordination workflows
• Source attribution — originating system recorded for audit and routing
• Timestamping — ISO 8601 UTC timestamps on create and update events

Next: Sandbox →

Purpose

Ecovira follows a sandbox-first integration model. Partners exercise the future API surface in an isolated environment before production credentials are considered. This supports staged rollout and operational readiness reviews.

Sandbox capabilities

Sandbox credentials

Sandbox API keys and organisation bindings will be issued to approved partners during onboarding — not through public self-serve signup. Keys are environment-scoped and separate from planned production credentials.

Example sandbox event

Emit a mock project update to exercise event ingestion and webhook fan-out.

{
  "event": "sandbox.project.updated",
  "project_id": "test_prj_0001",
  "status": "review_required",
  "environment": "sandbox"
}

Next: Authentication →

Access model

Authentication supports the staged rollout of Ecovira API Infrastructure.

• API keys — bearer tokens issued to approved partners per environment
• Environment separation — sandbox and production credentials are never interchangeable
• Partner-level permissions — access boundaries aligned with onboarding scope
• Scoped access — keys limited to approved modules and operations
• Rotation and revocation — planned lifecycle controls for credential hygiene

Authorization header

Include the API key on every request over HTTPS.

Authorization: Bearer eco_sk_live_xxxxxxxxx

Environments

Security principles

• Never expose secret keys client-side (browsers, mobile apps, or public repos)
• Rotate keys regularly as part of planned credential lifecycle
• Use environment-specific credentials — never reuse sandbox keys in production
• Restrict integrations by partner scope and approved modules
• Monitor webhook and event activity for anomalies during rollout

Error response

{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." } }

Next: Webhooks →

Webhook overview

Subscribe to events that matter for your integration. Planned webhook types include:

• Project updates and status transitions
• Payment and escrow status changes
• Document workflow events
• Partner alerts and coordination signals
• Review requirements and escalation notices

Delivery model

Example payload

{ "id": "evt_2048", "type": "project.updated", "created_at": "2026-05-25T04:00:00Z", "data": { "project_id": "eco_prj_1048", "status": "in_progress" } }

Verification

Verify webhook authenticity using the planned signature header. Compare against your webhook secret using HMAC-SHA256 over timestamp.payload.

Ecovira-Signature: t=1716614400,v1=8f4a2c...
Ecovira-Timestamp: 1716614400
Content-Type: application/json

Retry policy

Failed deliveries are planned to retry with exponential backoff: initial delay approximately 60 seconds, doubling per attempt, capped at one hour, with up to five attempts before dead-letter handling. Partners should respond with 2xx promptly and process idempotently using event IDs.

Next: Events →

Event philosophy

Every meaningful state change can emit an event with a stable identifier, typed name, source attribution, and timestamp. This supports webhook fan-out, audit trails, and cross-system coordination during staged rollout.

Event types

Event object

{ "id": "evt_2048", "type": "project.updated", "source": "workvira_nexus", "created_at": "2026-05-25T04:00:00Z", "data": {} }

Status lifecycle

Typical project coordination flow across the planned operational model:

Next: SDKs →

SDK roadmap

Ecovira is designing language-specific kits to reduce integration time for approved partners. Availability will follow staged rollout and partner feedback — there is no fully launched public SDK today.

Planned SDKs

Integration kits

Current recommendation

Until SDKs are released, use the API Reference, Sandbox examples, and Webhooks documentation. Request partner access when you are ready for governed credentials.

Next: Partner Access →