DEV Community

Prema Ananda
Prema Ananda Subscriber

Posted on

M2M API Integration Guide

#automation #api #tutorial #ai

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

M2M API Integration Guide

This document describes how external systems can interact with the AgentBounty API to create and manage tasks on behalf of existing users.

Overview

The main idea of M2M (Machine-to-Machine) interaction is to allow automated systems (e.g., bots, scripts, other backends) to launch AI agents. All tasks are securely linked to a real user, and payment for paid results is made by the user themselves in a secure browser environment.

The process is divided into two parts:

  1. Machine part: The M2M client creates and launches a task, then requests the result.
  2. Human part: If the result is paid, the user receives an email notification and completes the payment in the web interface.

Prerequisites

To interact with the M2M API, you need two things:

  1. Service Token (MCP_SERVICE_TOKEN):

    • What it is: A shared secret key that allows M2M systems access to special endpoints.
    • Where to get it: This token is located in the .env file of the main application. The administrator must securely provide it to the M2M client developer.

  2. User ID (user_id):

    • What it is: A unique user identifier from the Auth0 system, on whose behalf the task will be executed.
    • Why it's needed: The system needs to know who the "owner" of the task is to verify their existence and send them a payment link via email.
    • Where to get it: After logging into the AgentBounty web interface, the user_id is displayed in the site header under the username. It can be copied.

Step-by-Step M2M Interaction Process

Step 1: Creating a Task

The M2M client sends a POST request to a special endpoint to create a task.

  • Endpoint: POST /api/tasks/m2m/create
  • Headers:
    • Authorization: Bearer <your_MCP_SERVICE_TOKEN>
    • X-User-ID: <user_id>
    • Content-Type: application/json
  • Request Body (JSON): 
  {
      "agent_type": "factcheck",
      "input_data": {
          "text": "Does vitamin C cure the common cold?"
      }
  }
Enter fullscreen mode Exit fullscreen mode
  • Example curl request: 
  curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer f44ac472df45f1691156ab189d3108673c7f3dbf37cc1f3cab58cb37ea0f5c8d" \
  -H "X-User-ID: google-oauth2|112852885226533594909" \
  -d '{
      "agent_type": "factcheck",
      "input_data": { "text": "Does vitamin C cure the common cold?" }
  }' \
  http://localhost:8000/api/tasks/m2m/create
Enter fullscreen mode Exit fullscreen mode
  • Success Response (HTTP 201): The server will return a JSON object of the created task. Save the task id for the next steps. 
  {
      "id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "user_id": "google-oauth2|112852885226533594909",
      "agent_type": "factcheck",
      "status": "pending",
      ...
  }
Enter fullscreen mode Exit fullscreen mode

Create task

Step 2: Starting the Task

Immediately after creation, the task is in pending status. To start its execution, you need to send a POST request to the start endpoint.

  • Endpoint: POST /api/tasks/{task_id}/start
  • Headers:
    • Authorization: Bearer <your_MCP_SERVICE_TOKEN>
    • X-User-ID: <user_id>
  • Example curl request: 
  curl -X POST \
  -H "Authorization: Bearer f44ac472df45f1691156ab189d3108673c7f3dbf37cc1f3cab58cb37ea0f5c8d" \
  -H "X-User-ID: google-oauth2|112852885226533594909" \
  http://localhost:8000/api/tasks/fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3/start
Enter fullscreen mode Exit fullscreen mode

The task will begin executing in the background.

Step 3: Status Checking (Polling)

The M2M client should periodically poll the task status to find out when it's completed.

  • Endpoint: GET /api/tasks/{task_id}
  • Headers:
    • Authorization: Bearer <your_MCP_SERVICE_TOKEN>
    • X-User-ID: <user_id>
  • Response (when task is completed): The status field will change to completed. 
  {
      "id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "status": "completed",
      "actual_cost": 0.001,
      ...
  }
Enter fullscreen mode Exit fullscreen mode

Step 4: Requesting Result and Transferring Control to User

When the task is completed, the M2M client requests the result.

  • Endpoint: GET /api/tasks/{task_id}/result
  • Headers:
    • Authorization: Bearer <your_MCP_SERVICE_TOKEN>
    • X-User-ID: <user_id>

Possible Responses:

  1. If the result is free (actual_cost: 0): The server immediately returns the result.
  2. If the result is paid: The server returns the following JSON. This means the M2M client has completed its work at this stage, and now it's the user's turn. 
   {
       "status": "payment_link_sent",
       "message": "A link to complete the payment has been sent to the user's email.",
       "task_id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
       "amount": 0.001
   }
Enter fullscreen mode Exit fullscreen mode

At this moment, a "magic link" is sent to the user's email.

magic link

Step 5: Payment by User

  1. The user opens the email and clicks on the link like http://localhost:8000/?pay_task_id=....
  2. The website opens in the browser, the page scrolls to the needed task, and a modal window appears to confirm the payment.
  3. The user confirms the transaction in their crypto wallet (e.g., MetaMask).

Step 6: Retrieving the Paid Result

After the user has paid for the task, the M2M client (or any other client) can request the result again and this time receive it.

  • Endpoint: GET /api/tasks/{task_id}/result (same as in Step 4)
  • Headers: Same as before.
  • Success Response (HTTP 200): The server will return the full task result. 
  {
      "task_id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "status": "completed",
      "result_type": "text",
      "content": "## Post Summary...",
      ...
  }
Enter fullscreen mode Exit fullscreen mode

Result

The Role of Auth0 in the M2M Process

Auth0 plays a key, though not always obvious, role in ensuring the security and coherence of this process:

  1. User Existence Verification: When an M2M client sends a request with X-User-ID, our application doesn't blindly trust this ID. It immediately sends a request to the Auth0 Management API and asks: "Does a user with this ID exist?". If Auth0 responds "no", our server rejects the M2M request with a 404 Not Found error. This prevents the creation of "orphan tasks" on behalf of fictitious users.

  2. Obtaining Email for Notification: After successful user verification, when it's time to send the payment link, our application again contacts Auth0 and requests the user profile by their user_id. From this profile, we extract the email to which the notification is sent.

Thus, Auth0 acts as the single source of truth about users, allowing the M2M system to securely initiate actions that ultimately require the participation of a real, verified person.

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

Top comments (0)