N8n Task Status API: Backend Integration For Approvals

by Alex Johnson 55 views

In today's fast-paced digital landscape, automation is key to streamlining workflows and enhancing efficiency. One crucial aspect of automation, especially in AI-driven tasks, is ensuring proper approvals before execution. This article delves into the development of a robust Backend API for an Approvals System, focusing on the integration of n8n, a powerful workflow automation platform, to manage and verify the status of AI tasks. This system is designed to provide a critical layer of control, preventing the execution of unapproved tasks and ensuring compliance with organizational policies.

Objective: Building a Dedicated API Endpoint

The primary objective is to construct a dedicated API endpoint that facilitates the integration of n8n workflows with an approval system. This endpoint will empower the AI Task Executor to ascertain the approval status of tasks before they are executed. The importance of this endpoint cannot be overstated, as it serves as the final checkpoint to prevent unauthorized task executions. This is particularly vital in scenarios where tasks carry significant risk, necessitating stringent approval processes to avoid potential overreach.

Why is This Critical?

The endpoint acts as a gatekeeper, ensuring that all AI tasks undergo the necessary approval checks before being carried out. This is crucial for several reasons:

  1. Risk Mitigation: By verifying approvals, the system minimizes the risk of executing tasks that could have adverse consequences.
  2. Compliance: Adhering to approval workflows ensures that tasks comply with organizational policies and regulatory requirements.
  3. Control: The system provides a centralized point of control for managing task execution, enhancing transparency and accountability.
  4. Prevention of Automation Overreach: Automation can be a double-edged sword. Without proper controls, it can lead to unintended consequences. This endpoint ensures that automation remains within defined boundaries.

Background: The Need for Approval Verification

The existing n8n AI Task Executor workflow requires a mechanism to verify the approval status of tasks before they are executed. This verification process is essential for maintaining control and preventing unauthorized actions. The new API endpoint will provide several key functionalities:

  • Individual Task Status Check: Allows for the verification of the approval status of a single task.
  • Batch Status Queries: Enables efficient querying of the status of multiple tasks, optimizing performance for n8n workflows.
  • Idempotent, Cacheable Responses: Ensures that responses are consistent and can be cached to reduce load and improve response times.
  • Secure Authentication: Implements robust authentication mechanisms to protect the endpoint from unauthorized access.

This functionality is categorized as a Critical Risk task because it serves as the ultimate safeguard against unapproved task execution. In accordance with Risk-Based Robotic Framework (RBRF) principles, this system must effectively prevent automation overreach by guaranteeing that only tasks with proper authorization are executed.

Requirements: Defining the API Endpoints and Functionality

To meet the objectives and address the background context, a set of API endpoints and functionalities are required. These requirements are designed to provide a comprehensive solution for managing AI task approvals within the n8n workflow.

API Endpoints: The Core Interface

The API will consist of three primary endpoints, each designed to handle specific aspects of task approval status management.

GET /api/ai-tasks/:taskId/status

This endpoint is designed to check the approval status for a single task. It provides a detailed response containing information about the task's approval status, including whether it can be executed.

Response:

interface TaskApprovalStatus {
 taskId: string;
 approvalId: string | null;
 status: 'pending' | 'approved' | 'rejected' | 'expired' | 'no_approval_required';
 canExecute: boolean;
 blockedReason?: string;
 approvedAt?: string;
 approvedBy?: UserSummary[];
 expiresAt?: string;
 metadata?: {
 riskLevel: RiskLevel;
 category: string;
 requiredApprovers: number;
 currentApprovers: number;
 };
}
  • taskId: The unique identifier for the task.
  • approvalId: The identifier for the approval associated with the task (if any).
  • status: The current status of the approval, which can be pending, approved, rejected, expired, or no_approval_required.
  • canExecute: A boolean flag indicating whether the task can be executed based on its approval status.
  • blockedReason (optional): A string providing the reason why the task cannot be executed.
  • approvedAt (optional): The timestamp when the task was approved.
  • approvedBy (optional): An array of user summaries representing the users who approved the task.
  • expiresAt (optional): The timestamp when the approval expires.
  • metadata (optional): Additional metadata about the task, such as its risk level, category, and approval requirements.

POST /api/ai-tasks/status/batch

This endpoint facilitates batch status checks for multiple tasks, enhancing efficiency for n8n workflows. It accepts a list of task IDs and returns the approval status for each.

Request:

interface BatchStatusRequest {
 taskIds: string[]; // Max 100
}
  • taskIds: An array of task IDs for which to retrieve the status (maximum 100).

Response:

interface BatchStatusResponse {
 results: Record<string, TaskApprovalStatus>;
 meta: {
 totalQueried: number;
 approved: number;
 pending: number;
 rejected: number;
 };
}
  • results: A record containing the TaskApprovalStatus for each task ID.
  • meta: Metadata about the batch status check, including the total number of tasks queried, the number of approved tasks, the number of pending tasks, and the number of rejected tasks.

POST /api/ai-tasks/:taskId/execution-started

This endpoint is used to notify the system that a task execution has begun. It is called by n8n after the approval check to record the execution start.

Request:

interface ExecutionStartedRequest {
 workflowExecutionId: string;
 startedAt: string;
 metadata?: Record<string, any>;
}
  • workflowExecutionId: The identifier for the n8n workflow execution.
  • startedAt: The timestamp when the task execution started.
  • metadata (optional): Additional metadata about the execution.

Response:

interface ExecutionStartedResponse {
 acknowledged: boolean;
 taskId: string;
 executionId: string;
}
  • acknowledged: A boolean flag indicating whether the notification was successfully processed.
  • taskId: The identifier for the task.
  • executionId: The identifier for the task execution.

Authentication for n8n: Securing the Endpoints

To ensure the security of the API endpoints, a robust authentication mechanism is required. The chosen method is API key authentication, which is well-suited for automation systems like n8n.

  • API Key Authentication: Instead of user JWTs, API keys will be used to authenticate requests from n8n.
  • Scoped Keys: API keys will be scoped to only the specific endpoints required for task status management.
  • Rate Limiting: Rate limiting will be implemented to prevent abuse and ensure the stability of the API (1000 requests per minute for batch operations).
  • Optional IP Allowlisting: An optional IP allowlisting mechanism can be implemented to restrict access to the API from specific IP addresses.

The header format for authentication will be as follows:

// Header format
Authorization: Bearer ao-n8n-<api-key>
X-Workflow-ID: <n8n-workflow-id>
X-Execution-ID: <n8n-execution-id>
  • Authorization: The API key, prefixed with Bearer ao-n8n-.
  • X-Workflow-ID: The identifier for the n8n workflow.
  • X-Execution-ID: The identifier for the n8n execution.

Status Service: Logic and Functionality

A dedicated TaskStatusService will be responsible for handling the business logic related to task status management. This service will provide methods for retrieving task status, batch status, marking execution start, and internal helper functions.

interface TaskStatusService {
 getStatus(taskId: string): Promise<TaskApprovalStatus>;
 getBatchStatus(taskIds: string[]): Promise<BatchStatusResponse>;
 markExecutionStarted(taskId: string, executionInfo: ExecutionInfo): Promise<void>;
 
 // Internal helpers
 canTaskExecute(taskId: string): Promise<boolean>;
 getApprovalForTask(taskId: string): Promise<Approval | null>;
}
  • getStatus(taskId: string): Retrieves the approval status for a single task.
  • getBatchStatus(taskIds: string[]): Retrieves the approval status for a batch of tasks.
  • markExecutionStarted(taskId: string, executionInfo: ExecutionInfo): Marks the task as execution started.
  • canTaskExecute(taskId: string): An internal helper function to determine if a task can be executed.
  • getApprovalForTask(taskId: string): An internal helper function to retrieve the approval for a task.

Critical Safety Checks: Ensuring Secure Execution

To ensure that tasks are executed safely and in compliance with approval policies, several critical safety checks will be implemented.

  1. The system must return canExecute: false if:

    • No approval exists for the task.
    • The approval status is not approved.
    • The approval has expired.
    • The task was already executed.
    • The task status is not queued.

  2. The system must never return canExecute: true unless:

    • A valid approval exists with the status approved.
    • The approval is not expired.
    • The required approvers threshold is met.
    • The task is in a valid state for execution.

Caching Strategy: Optimizing Performance

To optimize performance and reduce the load on the system, a caching strategy will be implemented.

  • Status Responses Cacheable: Status responses will be cached for 30 seconds.
  • ETags for Conditional Requests: ETags will be used to support conditional requests, reducing the amount of data transferred.
  • Cache Invalidation: The cache will be invalidated on status changes to ensure that the cached data is always up-to-date.

Technical Approach: Implementing the API and Services

The technical approach involves the creation of controllers, services, and middleware to implement the API endpoints and functionalities. Each component will play a specific role in the overall system.

  1. Controller (src/app/api/ai-tasks/[taskId]/status/route.ts):

    • Handles the GET request for single task status.
    • Implements authentication middleware for n8n keys.
    • Sets caching headers.

  2. Batch Controller (src/app/api/ai-tasks/status/batch/route.ts):

    • Handles the POST request for batch queries.
    • Implements input validation (maximum 100 IDs).
    • Optimizes queries for parallel execution.

  3. Status Service (src/services/task-status.service.ts):

    • Implements the status determination logic.
    • Optimizes batch queries.
    • Manages the cache.

  4. n8n Auth Middleware (src/middleware/n8n-auth.ts):

    • Validates API keys.
    • Verifies the scope of the keys.
    • Logs requests.

Security / Legal Constraints: Ensuring Compliance and Protection

Security and legal constraints are paramount in the design and implementation of the API. The system must adhere to strict guidelines to protect against unauthorized access and ensure compliance with relevant regulations.

  • No Approval Bypass Paths: The system must not allow any bypass of the approval process.
  • Fail-Safe: In case of an error, the system must return canExecute: false to prevent unintended execution.
  • Log All Status Checks: All status checks must be logged for auditing purposes.
  • Audit Failed Execution Attempts: Any failed attempts to execute tasks must be audited.
  • Protect Against Replay Attacks: Measures must be implemented to protect against replay attacks.

Acceptance Criteria: Validating the System

The acceptance criteria define the conditions that must be met for the system to be considered successfully implemented. These criteria cover various aspects of the system, including functionality, performance, security, and integration.

  • [ ] Single task status returns accurate data.
  • [ ] Batch queries work efficiently (< 500ms for 100 tasks).
  • [ ] canExecute logic is bulletproof.
  • [ ] n8n authentication is working.
  • [ ] Caching improves performance.
  • [ ] Execution started notification is recorded.
  • [ ] Fail-safe returns false on errors.
  • [ ] All queries are logged for audit.
  • [ ] Integration tests with n8n workflow pass.
  • [ ] Load testing passed (1000 req/min).

Output to Produce: The Deliverables

The outputs to be produced as part of this project include the following files:

  1. src/app/api/ai-tasks/[taskId]/status/route.ts
  2. src/app/api/ai-tasks/status/batch/route.ts
  3. src/app/api/ai-tasks/[taskId]/execution-started/route.ts
  4. src/services/task-status.service.ts
  5. src/middleware/n8n-auth.ts
  6. src/schemas/task-status.schema.ts
  7. tests/api/task-status.test.ts

Dependencies: Required Components

This project has dependencies on other components and issues within the system.

  • Requires: Issue #17 (Database Schema)
  • Requires: Issue #20 (Decision Endpoint)

Part of Apex Orbis Approvals System - Phase 2: Backend APIs

Conclusion

The development of the n8n Task Status API is a critical step in ensuring the secure and controlled execution of AI tasks. By implementing robust approval checks, this system prevents automation overreach and ensures compliance with organizational policies. The API's design, with its focus on efficiency, security, and reliability, provides a solid foundation for future enhancements and integrations. This backend integration is a key component of the Apex Orbis Approvals System, contributing to a more secure and efficient workflow automation process. For more information on workflow automation best practices, consider visiting Zapier's Guide to Workflow Automation.