Getting Started

This guide will walk you through the entire process of setting up your first delegation mandate and verifying an action using the Mandaitor SDK.

1. Get your API Key

First, you need an API key to authenticate your requests. You can obtain one by signing up on the Mandaitor website.

Keep your API key secure and do not expose it in frontend applications.

2. Install the SDK

Install the Mandaitor TypeScript SDK in your project.

npm install @mandaitor/sdk

3. Initialize the Client

Create an instance of the MandaitorClient, providing your apiKey and tenantId.

import { MandaitorClient } from "@mandaitor/sdk";

const client = new MandaitorClient({
  apiKey: process.env.MANDAITOR_API_KEY, // Replace with your key
  tenantId: "tnt_your_tenant_id", // Replace with your tenant ID
});

4. Create a Mandate

Now, let's create a mandate that allows an AI agent to approve construction validations.

import type { CreateMandateRequest } from "@mandaitor/sdk";

async function createFirstMandate() {
  const request: CreateMandateRequest = {
    principal: {
      type: "HUMAN",
      subject_id: "user:jane.doe@example.com",
      display_name: "Jane Doe",
    },
    delegate: {
      type: "AI_AGENT",
      subject_id: "monco:agent:validation-v3",
      display_name: "Monco Validation Agent",
    },
    scope: {
      actions: ["construction.validation.approve"],
      resources: ["monco:project:proj_12345/*"],
      effect: "ALLOW",
    },
    constraints: {
      time: {
        // Mandate is valid for 30 days
        duration: "P30D",
      },
      rate_limits: {
        // Max 100 approvals per hour
        max_operations: 100,
        window_seconds: 3600,
      },
    },
  };

  try {
    const mandate = await client.createMandate(request);
    console.log("Mandate created:", mandate.mandate_id);
    return mandate;
  } catch (error) {
    console.error("Failed to create mandate:", error);
  }
}

5. Verify an Action

Once the mandate is created, you can use the verify endpoint to check if the agent is allowed to perform a specific action.

async function verifyAgentAction(mandateId: string) {
  try {
    const result = await client.verify({
      delegate_subject_id: "monco:agent:validation-v3",
      action: "construction.validation.approve",
      resource: "monco:project:proj_12345/zone:A/trade:electrical",
    });

    if (result.decision === "ALLOW") {
      console.log(`Action is allowed by mandate ${result.mandate_id}!`);
      // Proceed with the action...
    } else {
      console.log(`Action denied. Reason: ${result.reason_codes?.join(", ")}`);
    }
  } catch (error) {
    console.error("Verification failed:", error);
  }
}

// Assuming you have the mandate from the previous step
const newMandate = await createFirstMandate();
if (newMandate) {
  await verifyAgentAction(newMandate.mandate_id);
}

Congratulations! You have successfully created a mandate and verified an action against it. You can now explore more advanced features like React Integration or Proof-of-Mandate.