API Documentation on PlantCare Enterprise https://plantcare.farm/en/api/ Recent content in API Documentation on PlantCare Enterprise Hugo en-us Security & Authorization https://plantcare.farm/en/api/security/ Mon, 01 Jan 0001 00:00:00 +0000 https://plantcare.farm/en/api/security/ <p>The PlantCare Enterprise API implements a <strong>Zero Trust</strong> security model. Every request is authenticated at multiple layers to ensure data integrity and privacy.</p> <h2 id="1-client-to-api-authorization-api-keys">1. Client-to-API Authorization (API Keys)</h2> <p>Clients authenticate with a permanent <code>pk_ent_</code> key provided during onboarding. This key is validated by the <strong>Google Cloud API Gateway</strong>.</p> <div class="mermaid"> sequenceDiagram participant Client participant GW as "API Gateway" participant KV as "Secret Manager" participant API as "Backend Service" Client->>GW: "Request with Bearer pk_ent_..." GW->>KV: "Validate Key & Permissions" alt "Valid Key" GW->>API: "Proxy Request + Identity Headers" else "Invalid Key" GW-->>Client: "401 Unauthorized" end </div> <hr> <h2 id="2-storage-security-malware-scanning">2. Storage Security (Malware Scanning)</h2> <p>Every image uploaded to the Enterprise API is automatically scanned for viruses and malware before it is processed. This is handled by an asynchronous <strong>Cloud Storage Trigger</strong>.</p> The PlantCare Enterprise API implements a Zero Trust security model. Every request is authenticated at multiple layers to ensure data integrity and privacy.

1. Client-to-API Authorization (API Keys)

Clients authenticate with a permanent pk_ent_ key provided during onboarding. This key is validated by the Google Cloud API Gateway.

sequenceDiagram participant Client participant GW as "API Gateway" participant KV as "Secret Manager" participant API as "Backend Service" Client->>GW: "Request with Bearer pk_ent_..." GW->>KV: "Validate Key & Permissions" alt "Valid Key" GW->>API: "Proxy Request + Identity Headers" else "Invalid Key" GW-->>Client: "401 Unauthorized" end

2. Storage Security (Malware Scanning)

Every image uploaded to the Enterprise API is automatically scanned for viruses and malware before it is processed. This is handled by an asynchronous Cloud Storage Trigger.

sequenceDiagram participant GCS as "Cloud Storage" participant Func as "Scan Function" participant Scan as "Malware Scanner" GCS->>Func: "Event: Object Finalized" Func->>Scan: "OIDC Authorized Scan Request" Scan->>Scan: "Malware Signature Analysis" alt "Infected File" Scan-->>Func: "Status: infected" Func->>GCS: "DELETE Object" Func->>Func: "Log Security Incident" else "Clean File" Scan-->>Func: "Status: clean" end

3. Service-to-Service Authorization (OIDC)

When the Backend Service needs to call internal services (like the Image Processor), it does not use a shared secret. Instead, it uses OIDC ID Tokens fetched from the Google Metadata Server.

sequenceDiagram participant API as "Analyze Service" participant Meta as "GCP Metadata Server" participant Proc as "Image Processor" API->>Meta: "Fetch ID Token (Audience: Processor URL)" Meta-->>API: "Signed JWT ID Token" API->>Proc: "POST /process (Authorization: Bearer JWT)" Proc->>Proc: "Validate JWT with Google PubKeys" alt "Valid Token" Proc-->>API: "200 OK (Processed Image)" else "Invalid Token" Proc-->>API: "403 Forbidden" end

3. Network Isolation

To further harden the system, the Image Processor is configured with INGRESS_TRAFFIC_INTERNAL_ONLY. This means it is physically unreachable from the public internet, even with a valid token. Communication is routed through a private VPC Serverless Connector.

]]> Architecture & Scalability https://plantcare.farm/en/api/architecture/ Mon, 01 Jan 0001 00:00:00 +0000 https://plantcare.farm/en/api/architecture/ <p>The PlantCare Enterprise API is built on a <strong>Cloud-Native, Stateless</strong> architecture designed to handle massive IoT workloads with zero downtime.</p> <h2 id="1-edge-security--metering">1. Edge Security &amp; Metering</h2> <p>Every request to our Enterprise endpoints is intercepted by a high-performance <strong>Security Middleware</strong> that enforces security policies and usage quotas at the edge before any business logic is executed.</p> <div class="mermaid"> sequenceDiagram participant Client participant Edge as "Security Middleware" participant DB as "Quota/Audit Store" participant API as "Analyze Service" Client->>Edge: "Request (with API Token)" Edge->>Edge: "Validate Payload Size (<10MB)" Edge->>Edge: "Verify Token Format (API2)" Edge->>DB: "Check Quota & Role (RBAC)" alt "Quota Exceeded" Edge-->>Client: "429 Too Many Requests" else "Authorized" Edge->>DB: "Log Audit Trail" Edge->>API: "Forward Request" API-->>Client: "Analysis Result" end </div> <hr> <h2 id="2-reliable-webhook-delivery">2. Reliable Webhook Delivery</h2> <p>Our webhook system is decoupled from the main request lifecycle using <strong>Google Cloud Pub/Sub</strong>. This ensures that even if your endpoint is temporarily down, we will retry delivery with exponential backoff.</p> The PlantCare Enterprise API is built on a Cloud-Native, Stateless architecture designed to handle massive IoT workloads with zero downtime.

1. Edge Security & Metering

Every request to our Enterprise endpoints is intercepted by a high-performance Security Middleware that enforces security policies and usage quotas at the edge before any business logic is executed.

sequenceDiagram participant Client participant Edge as "Security Middleware" participant DB as "Quota/Audit Store" participant API as "Analyze Service" Client->>Edge: "Request (with API Token)" Edge->>Edge: "Validate Payload Size (<10MB)" Edge->>Edge: "Verify Token Format (API2)" Edge->>DB: "Check Quota & Role (RBAC)" alt "Quota Exceeded" Edge-->>Client: "429 Too Many Requests" else "Authorized" Edge->>DB: "Log Audit Trail" Edge->>API: "Forward Request" API-->>Client: "Analysis Result" end

2. Reliable Webhook Delivery

Our webhook system is decoupled from the main request lifecycle using Google Cloud Pub/Sub. This ensures that even if your endpoint is temporarily down, we will retry delivery with exponential backoff.

sequenceDiagram participant API as "Analyze Service" participant Topic as "Pub/Sub Topic" participant Worker as "Webhook Worker" participant Hub as "Client Endpoint" API->>Topic: "Publish: analysis.completed" API-->>API: "HTTP 202 Accepted" Topic->>Worker: "Trigger: New Event" Worker->>Worker: "Sign Payload (HMAC-SHA256)" Worker->>Hub: "POST (with PlantCare-Signature)" alt "Endpoint Down (5xx/4xx)" Hub-->>Worker: "Error" Worker->>Worker: "Retry with Exponential Backoff" else "Success (2xx)" Hub-->>Worker: "200 OK" end

3. Stateless Scalability

The Analyze Service is purely stateless. This allows the platform to:

  • Auto-Scale: Handle sudden traffic spikes by spawning hundreds of instances in seconds.
  • Self-Heal: If an instance fails, another one immediately takes its place without losing session state.
  • Global Reach: Deploy code to multiple GCP regions simultaneously for low-latency access.

4. Unified Analysis Pipeline

Our Go-based Enterprise API handles both mobile and third-party programmatic inputs through a single, intelligent endpoint.

  • Native Mobile Support: Automatically detects storagePath payloads from our mobile apps, utilizing optimized WebP files already present in our secure Cloud Storage buckets.
  • Programmatic Base64 Support: Accepts raw image data from enterprise clients, automatically handling secure ingestion, malware scanning, and optimization before AI analysis.
  • Multilingual Analysis: Enterprise clients and mobile users can specify a language parameter to receive localized diagnoses and care advice in their preferred language.
]]>