Skip to main content
API docs by Redocly

Mandaitor Delegation Mandate Registry API (1.0.0)

Download OpenAPI specification:Download

Mandaitor API Support: api@mandaitor.io License: Proprietary

Neutral, trustworthy infrastructure for verifiable delegated authority between humans and AI agents.

Admin

Admin-only operations

List onboarding access requests (admin only)

Lists onboarding access requests. Supports optional status filtering (PENDING, APPROVED, REJECTED) and cursor-based pagination. Requires Cognito JWT with mandaitor-admins group membership.

Authorizations:
BearerAuth
query Parameters
status
string
Enum: "PENDING" "APPROVED" "REJECTED"

Filter by request status

limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Base64url-encoded pagination cursor

Responses

Response samples

Content type
application/json
{
  • "requests": [
    ],
  • "next_cursor": "string"
}

Approve or reject an access request

Processes an admin action on an onboarding request. Supported values for {action}: approve, reject.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
requestId
required
string
action
required
string
Enum: "approve" "reject"
Request Body schema: application/json
notes
string

Responses

Request samples

Content type
application/json
{
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "company_name": "string",
  • "plan": "string",
  • "status": "ACTIVE",
  • "created_at": "2019-08-24T14:15:22Z",
  • "api_keys": [
    ]
}

Get tenant detail (admin)

Returns a single tenant's config, linked onboarding metadata, API key count, and mandate status counts (capped at the first 600 mandates).

Requires Cognito JWT with mandaitor-admins group membership.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: tnt_ABC123

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "display_name": "string",
  • "contact_name": "string",
  • "contact_email": "string",
  • "status": "ACTIVE",
  • "created_at": "2019-08-24T14:15:22Z",
  • "usage_plan": {
    },
  • "api_key_count": 0,
  • "mandate_stats": {
    },
  • "onboarding": {
    }
}

Emergency kill-switch — revoke all tenant mandates

EMERGENCY OPERATION — Immediately revokes all ACTIVE and SUSPENDED mandates for a tenant. This is an irreversible bulk operation intended for security incidents, compliance breaches, or contract terminations.

Requires Cognito JWT with mandaitor-admins group membership. A MANDATE_REVOKED audit event is emitted per mandate with details.kill_switch_triggered = true.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: tnt_ABC123
Request Body schema: application/json
required
reason
required
string

Mandatory reason for the emergency kill-switch

Responses

Request samples

Content type
application/json
{
  • "reason": "Security incident — unauthorized access detected"
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "revoked_count": 0,
  • "skipped_count": 0,
  • "execution_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get current system operational mode

Returns the current system mode (growth, sustain, maintenance, frozen) and associated metadata. Requires Cognito JWT with mandaitor-admins group membership.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "mode": "growth",
  • "reason": "Default operational mode",
  • "changed_at": "2019-08-24T14:15:22Z",
  • "changed_by": "string",
  • "estimated_duration_minutes": 0
}

Set system operational mode

Changes the system operational mode. This immediately affects all API endpoints:

  • growth — Normal operation. All features active.
  • sustain — Normal operation. No new features (policy only).
  • maintenance — All authenticated endpoints return 503.
  • frozen — Write endpoints return 503. Reads still work.

Mode changes propagate within ~10 seconds via in-memory cache TTL. Requires Cognito JWT with mandaitor-admins group membership.

Authorizations:
BearerAuth
Request Body schema: application/json
required
mode
required
string
Enum: "growth" "sustain" "maintenance" "frozen"
reason
string
estimated_duration_minutes
integer

Responses

Request samples

Content type
application/json
{
  • "mode": "maintenance",
  • "reason": "CDK stack update — estimated 30 minutes",
  • "estimated_duration_minutes": 30
}

Response samples

Content type
application/json
{
  • "mode": "growth",
  • "reason": "Default operational mode",
  • "changed_at": "2019-08-24T14:15:22Z",
  • "changed_by": "string",
  • "estimated_duration_minutes": 0
}

Authentication proxy for Cognito operations

Proxies authentication requests to Cognito from the browser, bypassing the ESC Cognito IDP endpoint DNS resolution issue. The {action} path parameter determines the operation:

  • login — InitiateAuth with USER_PASSWORD_AUTH
  • respond — RespondToAuthChallenge (NEW_PASSWORD_REQUIRED, MFA)
  • refresh — REFRESH_TOKEN_AUTH
  • sign-out — GlobalSignOut
  • forgot-password — ForgotPassword
  • confirm-forgot-password — ConfirmForgotPassword
path Parameters
action
required
string
Enum: "login" "respond" "refresh" "sign-out" "forgot-password" "confirm-forgot-password"
Request Body schema: application/json
required
object

Request body varies by action:

  • login: { email, password }
  • respond: { challengeName, session, responses }
  • refresh: { refreshToken }
  • sign-out: { accessToken }
  • forgot-password: { email }
  • confirm-forgot-password: { email, code, newPassword }

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Sync all tenants with Stripe Customers

Admin-only endpoint that scans all active tenants and creates Stripe Customer records for those that do not yet have one. Optionally creates a metered subscription if STRIPE_METERED_PRICE_ID is configured. Also runs automatically on a daily schedule (02:00 UTC).

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "synced": 0,
  • "skipped": 0,
  • "failed": 0,
  • "errors": [
    ]
}

Agent Marketplace

Agent discovery, catalog listings, capability matching, and reviews

Create a new marketplace listing

Authorizations:
BearerAuth
Request Body schema: application/json
required
agent_id
required
string
display_name
required
string
tagline
required
string <= 120 characters
description
required
string
logo_url
string <uri>
docs_url
string <uri>
required
Array of objects (CapabilityDeclaration) non-empty
required
object (PricingInfo)
tags
Array of strings
supported_regions
Array of strings
certifications
Array of strings

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ]
}

Response samples

Content type
application/json
{
  • "listing_id": "string",
  • "agent_id": "string",
  • "owner_tenant_id": "string",
  • "status": "DRAFT",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "trust_metrics": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

List own marketplace listings

Authorizations:
BearerAuth
query Parameters
cursor
string
limit
integer [ 1 .. 50 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Get listing details

Authorizations:
BearerAuth
path Parameters
listingId
required
string

Responses

Response samples

Content type
application/json
{
  • "listing_id": "string",
  • "agent_id": "string",
  • "owner_tenant_id": "string",
  • "status": "DRAFT",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "trust_metrics": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Update listing

Authorizations:
BearerAuth
path Parameters
listingId
required
string
Request Body schema: application/json
required
display_name
string
tagline
string <= 120 characters
description
string
logo_url
string <uri>
docs_url
string <uri>
Array of objects (CapabilityDeclaration)
object (PricingInfo)
tags
Array of strings
supported_regions
Array of strings
certifications
Array of strings

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ]
}

Response samples

Content type
application/json
{
  • "listing_id": "string",
  • "agent_id": "string",
  • "owner_tenant_id": "string",
  • "status": "DRAFT",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "trust_metrics": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Archive listing (soft-delete)

Authorizations:
BearerAuth
path Parameters
listingId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Publish a draft listing

Authorizations:
BearerAuth
path Parameters
listingId
required
string

Responses

Response samples

Content type
application/json
{
  • "listing_id": "string",
  • "agent_id": "string",
  • "owner_tenant_id": "string",
  • "status": "DRAFT",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "trust_metrics": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Suspend a published listing

Authorizations:
BearerAuth
path Parameters
listingId
required
string

Responses

Response samples

Content type
application/json
{
  • "listing_id": "string",
  • "agent_id": "string",
  • "owner_tenant_id": "string",
  • "status": "DRAFT",
  • "display_name": "string",
  • "tagline": "string",
  • "description": "string",
  • "logo_url": "http://example.com",
  • "docs_url": "http://example.com",
  • "capabilities": [
    ],
  • "pricing": {
    },
  • "trust_metrics": {
    },
  • "tags": [
    ],
  • "supported_regions": [
    ],
  • "certifications": [
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Discover agents (public)

query Parameters
q
string

Free-text search

category
string (CapabilityCategory)
Enum: "DOCUMENT_PROCESSING" "DATA_ANALYSIS" "COMMUNICATION" "FINANCIAL" "LEGAL" "COMPLIANCE" "IDENTITY" "INTEGRATION" "AUTOMATION" "CUSTOM"
min_trust_score
number [ 0 .. 1 ]
min_rating
number [ 1 .. 5 ]
pricing_model
string (PricingModel)
Enum: "FREE" "PER_CALL" "PER_MINUTE" "MONTHLY" "CUSTOM"
sort_by
string
Enum: "trust_score" "rating" "invocations" "response_time" "created_at"
sort_order
string
Enum: "asc" "desc"
cursor
string
limit
integer [ 1 .. 50 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "listings": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Find best-matching agents for a task

Authorizations:
BearerAuth
Request Body schema: application/json
required
task_description
required
string

Natural language description of the task

required_capabilities
Array of strings

Specific capability IDs needed

max_results
integer [ 1 .. 20 ]
Default: 5

Responses

Request samples

Content type
application/json
{
  • "task_description": "string",
  • "required_capabilities": [
    ],
  • "max_results": 5
}

Response samples

Content type
application/json
{
  • "listings": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Submit a review

Authorizations:
BearerAuth
Request Body schema: application/json
required
listing_id
required
string
rating
required
integer [ 1 .. 5 ]
comment
string
capability_id
string
consent_request_id
string

Responses

Request samples

Content type
application/json
{
  • "listing_id": "string",
  • "rating": 1,
  • "comment": "string",
  • "capability_id": "string",
  • "consent_request_id": "string"
}

Response samples

Content type
application/json
{
  • "review_id": "string",
  • "listing_id": "string",
  • "agent_id": "string",
  • "reviewer_tenant_id": "string",
  • "rating": 1,
  • "comment": "string",
  • "capability_id": "string",
  • "consent_request_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List reviews for a listing (public)

path Parameters
listingId
required
string
query Parameters
cursor
string
limit
integer [ 1 .. 50 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Delete own review

Authorizations:
BearerAuth
path Parameters
listingId
required
string
reviewId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Agent Registry

Agent Identity Registry — DID-based identity management for AI agents

Register a new AI agent identity

Creates a new agent identity with a DID, KMS-backed key pair, and initial ACTIVE status. The agent can then be bound to mandates.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
name
required
string

Human-readable agent name

description
string

Agent description

algorithm
string
Default: "ES256"
Enum: "ES256" "ES384" "EdDSA"

Key algorithm for the agent's verification method

object

Arbitrary metadata attached to the agent

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "algorithm": "ES256",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List registered agents

Returns a paginated list of agent identities for the authenticated tenant.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
status
string
Enum: "ACTIVE" "SUSPENDED" "REVOKED"
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Base64url-encoded pagination cursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Get agent details

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Resolve agent DID Document

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/did+json
{ }

Rotate agent cryptographic key

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
algorithm
string
Default: "ES256"
Enum: "ES256" "ES384" "EdDSA"

Responses

Request samples

Content type
application/json
{
  • "algorithm": "ES256"
}

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Bind agent to a mandate

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
mandate_id
required
string

Responses

Request samples

Content type
application/json
{
  • "mandate_id": "string"
}

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Unbind agent from a mandate

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
mandateId
required
string

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Suspend an agent

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reactivate a suspended agent

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Permanently revoke an agent

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "tenant_id": "string",
  • "did": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "verification_methods": [
    ],
  • "bound_mandates": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Billing

Pay-per-use billing, usage tracking, and payment management

Get usage data for a tenant

Returns usage data for the authenticated tenant's current or specified billing period. Includes total units, per-endpoint breakdown, daily usage timeline, and per-API-key breakdown. The tenant path parameter must match the authenticated caller.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
query Parameters
period
string^\d{4}-\d{2}$
Example: period=2026-04

Billing period in YYYY-MM format. Defaults to current month.

granularity
string
Default: "daily"
Enum: "daily" "hourly"

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "billing_period": "2026-04",
  • "total_units": 0,
  • "endpoint_breakdown": {
    },
  • "daily_usage": [
    ],
  • "api_key_breakdown": [
    ],
  • "granularity": "daily"
}

Get billing status and invoice history

Returns the billing status for the authenticated tenant, including Stripe subscription details, payment method status, recent invoices, current period usage, and a link to the Stripe Customer Portal for managing payment methods. The tenant path parameter must match the authenticated caller.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "billing_status": "active",
  • "stripe_connected": true,
  • "subscription_status": "string",
  • "subscription": {
    },
  • "invoices": [
    ],
  • "current_period": {
    },
  • "portal_url": "http://example.com"
}

Create a Stripe SetupIntent for card collection

Creates a Stripe SetupIntent to securely collect a payment method (credit card) for the tenant. If the tenant does not yet have a Stripe Customer, one is created automatically. Returns a client secret for use with Stripe.js / Stripe Elements on the frontend.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "client_secret": "string",
  • "stripe_customer_id": "string"
}

Create or update a subscription for a pricing plan

Creates or updates a Stripe Subscription for the tenant based on the selected pricing plan. For the free beta plan, no Stripe subscription is created and no payment method is required. For paid plans (starter, growth, enterprise), a Stripe subscription is created with metered billing. If the tenant has no payment method on file, a SetupIntent client_secret is returned so the frontend can collect card details.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
plan
required
string
Enum: "beta" "starter" "growth" "enterprise"

The pricing plan to subscribe to

Responses

Request samples

Content type
application/json
{
  • "plan": "beta"
}

Response samples

Content type
application/json
{
  • "plan": "beta",
  • "plan_name": "string",
  • "status": "active",
  • "requires_payment": true,
  • "subscription_id": "string",
  • "stripe_customer_id": "string",
  • "client_secret": "string",
  • "message": "string"
}

Stripe webhook endpoint

Receives and processes Stripe webhook events. Authentication is performed via Stripe signature verification (not API key or JWT). Handles invoice lifecycle events (payment succeeded/failed/finalized) and subscription changes (updated/deleted).

Request Body schema: application/json
required
object

Raw Stripe webhook event payload

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "received": true
}

Sync all tenants with Stripe Customers

Admin-only endpoint that scans all active tenants and creates Stripe Customer records for those that do not yet have one. Optionally creates a metered subscription if STRIPE_METERED_PRICE_ID is configured. Also runs automatically on a daily schedule (02:00 UTC).

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "synced": 0,
  • "skipped": 0,
  • "failed": 0,
  • "errors": [
    ]
}

Consent

Human-in-the-Loop consent approval flows with auto-approval policies

Create a consent request for human-in-the-loop approval

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
mandate_id
required
string

ID of the mandate being acted upon

agent_id
required
string

ID of the agent requesting consent

requested_actions
required
Array of strings

Actions the agent wants to perform

requested_resources
required
Array of strings

Resources the agent wants to access

reason
required
string

Human-readable explanation of why consent is needed

context
object

Additional context for the consent decision

expires_in_seconds
integer

Custom TTL for this consent request (default 3600)

Responses

Request samples

Content type
application/json
{
  • "mandate_id": "string",
  • "agent_id": "string",
  • "requested_actions": [
    ],
  • "requested_resources": [
    ],
  • "reason": "string",
  • "context": { },
  • "expires_in_seconds": 0
}

Response samples

Content type
application/json
{
  • "consent_id": "string",
  • "tenant_id": "string",
  • "mandate_id": "string",
  • "agent_id": "string",
  • "approver_subject_id": "string",
  • "status": "pending",
  • "requested_actions": [
    ],
  • "requested_resources": [
    ],
  • "reason": "string",
  • "context": { },
  • "resolution": {
    },
  • "auto_approved": true,
  • "policy_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

List pending consent requests for the authenticated user

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer
Default: 20
cursor
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Get a consent request by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "consent_id": "string",
  • "tenant_id": "string",
  • "mandate_id": "string",
  • "agent_id": "string",
  • "approver_subject_id": "string",
  • "status": "pending",
  • "requested_actions": [
    ],
  • "requested_resources": [
    ],
  • "reason": "string",
  • "context": { },
  • "resolution": {
    },
  • "auto_approved": true,
  • "policy_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Approve or reject a consent request

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
decision
required
string
Enum: "approved" "rejected"
reason
string

Reason for the decision

conditions
object

Optional conditions attached to the approval

Responses

Request samples

Content type
application/json
{
  • "decision": "approved",
  • "reason": "string",
  • "conditions": { }
}

Response samples

Content type
application/json
{
  • "consent_id": "string",
  • "tenant_id": "string",
  • "mandate_id": "string",
  • "agent_id": "string",
  • "approver_subject_id": "string",
  • "status": "pending",
  • "requested_actions": [
    ],
  • "requested_resources": [
    ],
  • "reason": "string",
  • "context": { },
  • "resolution": {
    },
  • "auto_approved": true,
  • "policy_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

List consent requests for a specific mandate

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
query Parameters
status
string
Enum: "pending" "approved" "rejected" "expired"
limit
integer
Default: 20
cursor
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Create an auto-approval policy

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
name
required
string

Human-readable policy name

description
string
required
Array of objects (ConsentPolicyRule)
priority
integer

Higher priority policies are evaluated first (default 0)

enabled
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "rules": [
    ],
  • "priority": 0,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "description": "string",
  • "rules": [
    ],
  • "priority": 0,
  • "enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List consent policies for the tenant

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer
Default: 20
cursor
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "total_count": 0
}

Get a consent policy by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "description": "string",
  • "rules": [
    ],
  • "priority": 0,
  • "enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a consent policy

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
Array of objects (ConsentPolicyRule)
priority
integer
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "rules": [
    ],
  • "priority": 0,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "description": "string",
  • "rules": [
    ],
  • "priority": 0,
  • "enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a consent policy

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Drift Monitor

@experimental Behavioural drift monitoring for delegated agents

List agents with drift summaries

@experimental Aggregates drift session data across all mandates to produce per-agent summaries including average/max drift scores, session counts, and last activity timestamps.

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List recent drift detection events

@experimental Queries the events table for DRIFT_DETECTED and DRIFT_RESOLVED events, enriched with the drift score from the event details.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of events to return.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List drift sessions for a specific agent

@experimental Queries the drift sessions table to retrieve all recent session windows for a given delegate, enriched with computed drift scores and mandate context.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
delegateId
required
string

The delegate subject ID.

query Parameters
hours
integer [ 1 .. 168 ]
Default: 24

Lookback window in hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

EUDI Wallet

eIDAS 2.0 EUDI Wallet identity verification (OpenID4VP)

Initiate EUDI Wallet verification session

Creates a new OpenID4VP session for EUDI Wallet identity verification. Returns a QR code URI (cross-device) and deep link URI (same-device) that the user scans/opens with their EUDI Wallet.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
optional
presentation_definition_id
string
Default: "mandaitor-pid-standard"
Enum: "mandaitor-pid-minimal" "mandaitor-pid-standard" "mandaitor-pid-delegation"

ID of the presentation definition to use

Responses

Request samples

Content type
application/json
{
  • "presentation_definition_id": "mandaitor-pid-minimal"
}

Response samples

Content type
application/json
{
  • "session_id": "eudi_01HXYZ...",
  • "status": "PENDING",
  • "request_uri": "http://example.com",
  • "qr_code_uri": "string",
  • "deep_link_uri": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Poll EUDI session status

Polls the status of an EUDI Wallet verification session. Returns the resolved identity when the session is completed.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{
  • "session_id": "string",
  • "status": "PENDING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "presentation_definition_id": "string",
  • "resolved_identity": {
    },
  • "verified_at": "2019-08-24T14:15:22Z",
  • "errors": [
    ]
}

Receive VP Token from EUDI Wallet

Receives the VP Token from the EUDI Wallet via direct_post response mode. This endpoint is called by the wallet after user consent. No authentication required as the wallet POSTs directly.

path Parameters
sessionId
required
string
Request Body schema:
required
vp_token
required
string

The VP Token (SD-JWT VC compact serialization)

presentation_submission
object

DIF Presentation Submission mapping

Responses

Request samples

Content type
{
  • "vp_token": "string",
  • "presentation_submission": { }
}

Response samples

Content type
application/json
{
  • "status": "COMPLETED",
  • "session_id": "string"
}

Serve OpenID4VP Authorization Request Object

Serves the signed JWT Authorization Request Object that the EUDI Wallet fetches after scanning the QR code. Returns the JWT directly with content type application/oauth-authz-req+jwt.

path Parameters
requestId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Events

Immutable audit trail

Get audit events for a mandate

Returns a paginated list of audit events for a specific mandate. Events form an immutable, hash-chained audit trail.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Base64url-encoded pagination cursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Query all events for the tenant

Queries all audit events for the authenticated tenant, filtered by mandate_id. Supports optional event_type filtering and cursor-based pagination.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
mandate_id
required
string

Mandate ID to filter events by

event_type
string
Enum: "MANDATE_CREATED" "MANDATE_SUSPENDED" "MANDATE_REACTIVATED" "MANDATE_REVOKED" "VERIFICATION_ALLOWED" "VERIFICATION_DENIED" "ESCALATION_TRIGGERED"
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Base64url-encoded pagination cursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Get a specific event by ID

Retrieves a single audit event by its ID. Requires the mandate_id query parameter to locate the event in the partition.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: evt_01HXYZ...
query Parameters
mandate_id
required
string

Mandate ID the event belongs to

Responses

Response samples

Content type
application/json
{
  • "event_id": "string",
  • "tenant_id": "string",
  • "mandate_id": "string",
  • "event_type": "MANDATE_CREATED",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "actor": {
    },
  • "details": { },
  • "previous_event_hash": "string",
  • "event_hash": "string",
  • "kms_signature": "string",
  • "hash_algorithm": "SHA_256",
  • "signing_algorithm": "RSASSA_PSS_SHA_256"
}

List audit events for the tenant (all mandates)

Tenant-scoped audit feed used by the dashboard Overview / Recent Activity. Returns events in descending timestamp order across all of the tenant's mandates. For a per-mandate timeline use GET /events?mandate_id=… instead. The tenant path parameter must match the authenticated caller. Requires Cognito JWT.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Opaque base64url cursor from a previous response's next_cursor.

event_type
string

Optional filter on event_type (applied after the tenant-scoped query).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Export tenant audit events for SIEM ingestion

Exports a tenant-scoped audit event slice in descending timestamp order for SIEM, GRC, and offline audit tooling. The tenant path parameter must match the authenticated caller unless the caller is a platform admin. Requires the events:export permission, which is granted to tenant administrators and tenant auditors.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
query Parameters
limit
integer [ 1 .. 500 ]
Default: 100

Maximum number of audit events to include in this export page.

cursor
string

Opaque base64url cursor from a previous response's next_cursor.

event_type
string

Optional filter on event_type for SIEM-specific routing or replay windows.

from_timestamp
string <date-time>

Inclusive lower bound for the audit-event timestamp sort key.

to_timestamp
string <date-time>

Inclusive upper bound for the audit-event timestamp sort key.

Responses

Response samples

Content type
application/json
{
  • "export_id": "audexp_dG50X2FjbWU6MjAyNi0wNS0xOVQxMjozMDowMFowMDBa",
  • "tenant_id": "string",
  • "generated_at": "2019-08-24T14:15:22Z",
  • "event_count": 0,
  • "items": [
    ],
  • "next_cursor": "string"
}

Evidence

Export a court-ready evidence pack

Exports a comprehensive, court-ready evidence pack for a mandate containing:

  • Mandate snapshot at export time
  • Hash-chained audit event log
  • SD-JWT proof tokens from verification events
  • Case log hash (SHA-256 fingerprint over canonical event chain)
  • Export manifest with requester attribution, coverage, and recomputable digests
  • Immutable EVIDENCE_PACK_EXPORTED audit event recorded for the export operation
  • Issuer DID document reference for independent verification

The case_log_hash is a deterministic SHA-256 digest computed over the canonical JSON representation of the event chain, enabling tamper detection.

The export_manifest binds the mandate snapshot, event chain, proof tokens, and export envelope to recomputable digests so offline reviewers can detect tampering in the export artifact.

The schema_version field allows forward-compatible evolution of the pack format.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
query Parameters
event_id
string

Scope the evidence pack to a specific verification event

Responses

Response samples

Content type
application/json
{
  • "schema_version": "1.2.0",
  • "export_timestamp": "2019-08-24T14:15:22Z",
  • "tenant_id": "string",
  • "mandate_id": "string",
  • "mandate_snapshot": { },
  • "event_chain": [
    ],
  • "event_count": 0,
  • "case_log_hash": "string",
  • "chain_integrity": {
    },
  • "issuer": {},
  • "proof_tokens": [
    ],
  • "crypto_metadata": {
    },
  • "export_manifest": {
    },
  • "metadata": {
    }
}

Identity

Identity provider configuration, token exchange, and SCIM provisioning

Get tenant identity provider configuration

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "identity_providers": {
    }
}

Update tenant identity provider configuration

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
enabled_providers
required
Array of strings
Items Enum: "API_KEY" "COGNITO" "EUDI_WALLET" "AUTH0" "OKTA" "ENTRA_ID" "GOOGLE" "AWS_IAM_IDC" "GENERIC_OIDC"
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "enabled_providers": [
    ],
  • "auth0": {
    },
  • "okta": {},
  • "entra": {
    },
  • "eudi": {
    },
  • "google": {
    },
  • "aws_iam_idc": {},
  • "generic_oidc": {}
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "identity_providers": {
    }
}

OAuth 2.0 Token Exchange for delegation chains

Exchange a user's access token for a scoped delegation token. Implements RFC 8693 Token Exchange for On-Behalf-Of (OBO) flows where AI agents act on behalf of authenticated users.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
subject_token
required
string

The original user's access token

subject_token_type
string
Default: "urn:ietf:params:oauth:token-type:access_token"
mandate_id
required
string

Mandate ID that authorizes the delegation

scope
string
audience
string

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  • "mandate_id": "string",
  • "scope": "string",
  • "audience": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "string",
  • "issued_token_type": "string",
  • "delegation": {
    }
}

List tenant role assignments

Returns the persisted role-assignment policy rows for a tenant. Each assignment binds a canonical subject ID to tenant-scoped roles and derived effective permissions. The tenant path parameter must match the authenticated caller unless the caller is a platform administrator. Requires tenant:read permission.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "assignments": [
    ]
}

Create or update a tenant role assignment

Creates or replaces the tenant-scoped role assignment for the canonical subject ID in the path. platform_admin and platform:* grants are rejected because tenant policy can only delegate tenant-scoped access. Role-derived permissions and any explicit tenant permissions are stored as the assignment's effective permission set. Emits an immutable TENANT_ROLE_ASSIGNED audit event. Requires tenant:write permission.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
subjectId
required
string [ 3 .. 256 ] characters ^[A-Za-z0-9._:@/-]{3,256}$
Example: eudi:DE/1234567890abcdef

URL-encoded canonical subject ID resolved by the authorizer.

Request Body schema: application/json
required
subject_type
string (TenantSubjectType)
Enum: "NATURAL_PERSON" "LEGAL_ENTITY" "SERVICE" "AGENT"
display_name
string [ 1 .. 200 ] characters
email
string <email> <= 320 characters
roles
required
Array of strings (RbacRole) [ 1 .. 5 ] items
Items Enum: "platform_admin" "tenant_admin" "tenant_operator" "tenant_auditor" "tenant_viewer" "service"

Tenant-assignable RBAC roles. platform_admin is rejected for this endpoint.

permissions
Array of strings (RbacPermission) <= 30 items
Items Enum: "*" "platform:admin" "platform:onboarding:read" "platform:onboarding:write" "platform:tenants:read" "platform:tenants:write" "tenant:read" "tenant:write" "tenant:billing:read" "tenant:usage:read" "tenant:audit:read" "tenant:api-keys:read" "tenant:api-keys:write" "mandates:read" "mandates:write" "verify:execute" "events:read" "events:export" "evidence:read" "evidence:write"

Optional explicit tenant-scoped permissions merged with role-derived grants. Platform permissions are rejected.

Responses

Request samples

Content type
application/json
{
  • "subject_type": "NATURAL_PERSON",
  • "display_name": "Amina Bauer",
  • "email": "amina.bauer@example.com",
  • "roles": [
    ],
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "assignment": {
    }
}

Revoke a tenant role assignment

Revokes the tenant-scoped role assignment for the canonical subject ID by deleting the persisted policy row. The next authorizer evaluation no longer enriches the subject with those tenant roles or permissions. Emits an immutable TENANT_ROLE_REVOKED audit event. The operation is idempotent. Requires tenant:write permission.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
subjectId
required
string [ 3 .. 256 ] characters ^[A-Za-z0-9._:@/-]{3,256}$
Example: oidc:okta:00u123456789

URL-encoded canonical subject ID resolved by the authorizer.

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Mandates

Core mandate lifecycle operations

Create a new mandate

Creates a new delegation mandate between a principal and a delegate. The mandate defines the scope of delegated authority, optional constraints, and an expiration date. A KMS-signed audit event is emitted on success.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
object (Subject)

Represents an entity (human, AI agent, service, or organization) that participates in a mandate as either principal or delegate.

required
object (Subject)

Represents an entity (human, AI agent, service, or organization) that participates in a mandate as either principal or delegate.

required
object (Scope)

Defines the actions, resources, and effect (ALLOW/DENY) that a mandate authorizes, with optional conditions.

object (Constraints)

Optional restrictions on mandate usage including time windows, geographic fencing, MFA requirements, IP whitelisting, and escalation rules.

metadata
object
expires_at
string <date-time>
taxonomy_id
string

Taxonomy identifier to validate the mandate scope against (e.g., "construction", "realestate", "venture").

taxonomy_version
string^[a-z][a-z0-9-]*(@\d+\.\d+\.\d+(-[a-z0-9.]+)?...

Versioned taxonomy reference. Accepts either a plain ID (uses latest version) or id@semver format (validates exact version match).

require_approval
boolean
Default: false

When true, the mandate starts in PENDING_APPROVAL status and requires explicit approval before becoming ACTIVE.

object (MandateIntent)

@experimental Intent declaration for drift detection. Allows the principal to express the intended purpose and expected behavioral clusters for a mandate. Used by the drift detection engine to compute semantic distance scores.

object (VUIRequest)

@experimental Verifiable User Instruction input. Captures the human's original instruction at mandate creation time. The instruction text will be encrypted at rest and its SHA-256 digest embedded into the Proof-of-Mandate Verifiable Credential.

Responses

Request samples

Content type
application/json
{
  • "principal": {
    },
  • "delegate": {
    },
  • "scope": {
    },
  • "constraints": {
    },
  • "metadata": { },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "taxonomy_id": "construction",
  • "taxonomy_version": "construction@2.0.0",
  • "require_approval": false,
  • "intent": {
    },
  • "vui": {
    }
}

Response samples

Content type
application/json
{
  • "mandate_id": "mdt_01HXYZ...",
  • "tenant_id": "string",
  • "version": 0,
  • "status": "DRAFT",
  • "principal": {
    },
  • "delegate": {
    },
  • "scope": {
    },
  • "constraints": {
    },
  • "proof": {
    },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "vui": {
    }
}

List mandates (paginated)

Returns a paginated list of mandates for the authenticated tenant. Supports optional filtering by status and cursor-based pagination.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
status
string
Enum: "DRAFT" "ACTIVE" "SUSPENDED" "REVOKED" "EXPIRED"
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string

Base64url-encoded pagination cursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Get mandate by ID

Retrieves a single mandate by its ID. Returns the full mandate record including principal, delegate, scope, constraints, and proof metadata.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...

Responses

Response samples

Content type
application/json
{
  • "mandate_id": "mdt_01HXYZ...",
  • "tenant_id": "string",
  • "version": 0,
  • "status": "DRAFT",
  • "principal": {
    },
  • "delegate": {
    },
  • "scope": {
    },
  • "constraints": {
    },
  • "proof": {
    },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "vui": {
    }
}

Revoke a mandate

Permanently revokes a mandate. Only active or suspended mandates can be revoked. An optional reason can be provided. A KMS-signed audit event is emitted.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
Request Body schema: application/json
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "Contract terminated"
}

Response samples

Content type
application/json
{
  • "mandate_id": "string",
  • "status": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Suspend a mandate

Temporarily suspends an active mandate. Suspended mandates can be reactivated later. An optional reason can be provided.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
Request Body schema: application/json
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "Under review"
}

Response samples

Content type
application/json
{
  • "mandate_id": "string",
  • "status": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reactivate a suspended mandate

Reactivates a previously suspended mandate, returning it to ACTIVE status. Only mandates in SUSPENDED state can be reactivated.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...

Responses

Response samples

Content type
application/json
{
  • "mandate_id": "string",
  • "status": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Approve a pending mandate

Approves a mandate that is in PENDING_APPROVAL state, transitioning it to ACTIVE. Only mandates created with require_approval: true enter this state. An audit event (MANDATE_APPROVED) is emitted.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
Request Body schema: application/json
reason
string

Optional reason/notes for the approval

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "mandate_id": "string",
  • "status": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reject a pending mandate

Rejects a mandate that is in PENDING_APPROVAL state, transitioning it to REVOKED. An audit event (MANDATE_REJECTED) is emitted.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
Request Body schema: application/json
reason
string

Reason for rejection

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "mandate_id": "string",
  • "status": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve the decrypted user instruction for a mandate

Returns the decrypted original user instruction that was provided when the mandate was created. Requires authentication and tenant ownership. An INSTRUCTION_REVEALED audit event is emitted on each access.

Only available for mandates that were created with a Verifiable User Instruction (VUI). Returns 404 if no instruction exists.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...

Responses

Response samples

Content type
application/json
{
  • "instruction_text": "string",
  • "instruction_hash": "string",
  • "instruction_timestamp": "2019-08-24T14:15:22Z",
  • "instruction_channel": "chat",
  • "principal_confirmation": {
    },
  • "mandate_id": "string"
}

MCP Authorization

MCP Authorization Server — OAuth-based tool call authorization for AI agents

MCP OAuth Authorization Server Metadata

Returns the OAuth 2.0 Authorization Server Metadata for the MCP authorization endpoint. Used by MCP clients to discover token and authorization endpoints.

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "token_endpoint": "string",
  • "authorization_endpoint": "string",
  • "grant_types_supported": [
    ],
  • "token_endpoint_auth_methods_supported": [
    ],
  • "scopes_supported": [
    ],
  • "mcp_tool_namespaces": [
    ],
  • "mandate_enforcement": "strict"
}

Exchange agent credentials for MCP access token

OAuth 2.0 client_credentials grant for MCP agents. The agent presents a signed JWT assertion and receives a scoped access token bound to its mandates.

Request Body schema: application/json
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string

Agent DID

client_assertion_type
required
string
Value: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion
required
string

Signed JWT assertion

scope
string

Space-separated mandate scopes

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  • "client_assertion": "string",
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "scope": "string"
}

Authorize an MCP tool call against mandates

Evaluates whether a tool call is authorized by the agent's bound mandates. Returns ALLOW, DENY, or ESCALATE with constraint details.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
tool_name
required
string

Fully qualified MCP tool name

required
object

Tool call arguments

object

Additional context for authorization

Responses

Request samples

Content type
application/json
{
  • "tool_name": "string",
  • "arguments": { },
  • "context": { }
}

Response samples

Content type
application/json
{
  • "decision": "ALLOW",
  • "reason": "string",
  • "pom_token": "string",
  • "approval_request_id": "string",
  • "applied_constraints": {
    },
  • "drift_score": 0.1
}

Get MCP session details

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "session_id": "string",
  • "tenant_id": "string",
  • "agent_id": "string",
  • "agent_did": "string",
  • "mandate_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "last_active_at": "2019-08-24T14:15:22Z",
  • "call_count": 0
}

Onboarding

Tenant access request and activation

Submit an access request (no auth required)

Submits a new tenant access request. No authentication required. The request enters PENDING state and must be approved by an admin.

Request Body schema: application/json
required
company_name
required
string
contact_name
string
contact_email
required
string <email>
use_case
required
string
industry
string
Enum: "construction" "real_estate" "venture_capital" "other"
website
string <uri>
lead_source
string

Marketing or referral source associated with the beta request.

beta_track
string

Closed-beta routing segment used for the request.

asset
string

Specific public asset or CTA entry point that produced the request.

Responses

Request samples

Content type
application/json
{
  • "company_name": "monco GmbH",
  • "contact_name": "Max Mustermann",
  • "contact_email": "max@monco.ai",
  • "use_case": "AI agent delegation for construction validation",
  • "industry": "construction",
  • "website": "http://example.com",
  • "lead_source": "trust-site",
  • "beta_track": "construction",
  • "asset": "home-hero"
}

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "status": "PENDING",
  • "message": "string"
}

List API keys for the tenant (metadata only)

Returns metadata for every API key owned by the tenant. The raw key is only available at creation time via POST /tenants/{id}/api-keys; this endpoint never returns the raw key or its hash. The tenant is taken from the authenticated caller — the path parameter must match, or the request is rejected with 403. Requires Cognito JWT.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Generate a new API key for the tenant

Generates a new API key for a tenant. The raw key is returned only once in the response and cannot be retrieved again. Requires Cognito JWT.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
name
string
environment
string
Default: "live"
Enum: "live" "test"
scopes
Array of strings (ApiScope)
Items Enum: "mandates:read" "mandates:write" "verify"

Scope list the issued key will be allowed to exercise. Omitted or null means "all canonical scopes" — equivalent to passing ["mandates:read","mandates:write","verify"]. An empty array issues an inert key. Unknown scopes are rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "name": "production-key",
  • "environment": "live",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "key_id": "string",
  • "api_key": "string",
  • "name": "string",
  • "environment": "live",
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Revoke an API key for the tenant

Flips the per-key row to status: "REVOKED". The authorizer reads per-key rows directly, so the key stops authenticating on the next request — other ACTIVE keys for the same tenant keep working. Idempotent for already-revoked keys. The tenant path parameter must match the authenticated caller. Requires Cognito JWT.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
keyId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Public

Unauthenticated public endpoints

Health/status check

Returns service health status. No sensitive data is exposed. Suitable for monitoring, load balancers, and Trust Center embedding.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "version": "1.2.3-beta.1",
  • "stage": "prod"
}

Resolve the Mandaitor issuer DID document

Returns the W3C DID Document for the Mandaitor issuer DID (did:web:api.mandaitor.io). Contains the public key used to verify Proof-of-Mandate SD-JWT VCs.

Responses

Response samples

Content type
application/did+json
{
  • "@context": [
    ],
  • "id": "did:web:api.mandaitor.io",
  • "verificationMethod": [
    ],
  • "authentication": [
    ],
  • "assertionMethod": [
    ],
  • "service": [
    ]
}

Public trust signals for machine-readable trust metadata

Returns machine-readable trust metadata including region, partition, issuer DID, data residency claims, and supported open standards. Unauthenticated and cache-friendly (5-minute client, 10-minute CDN).

Responses

Response samples

Content type
application/json
{
  • "schema_version": "1.0.0",
  • "region": "eusc-de-east-1",
  • "partition": "aws-eusc",
  • "issuer_did": "did:web:api.mandaitor.io",
  • "did_document_url": "https://api.mandaitor.io/.well-known/did.json",
  • "data_residency": {
    },
  • "open_standards": [
    ],
  • "build_version": "string",
  • "stage": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Submit an access request (no auth required)

Submits a new tenant access request. No authentication required. The request enters PENDING state and must be approved by an admin.

Request Body schema: application/json
required
company_name
required
string
contact_name
string
contact_email
required
string <email>
use_case
required
string
industry
string
Enum: "construction" "real_estate" "venture_capital" "other"
website
string <uri>
lead_source
string

Marketing or referral source associated with the beta request.

beta_track
string

Closed-beta routing segment used for the request.

asset
string

Specific public asset or CTA entry point that produced the request.

Responses

Request samples

Content type
application/json
{
  • "company_name": "monco GmbH",
  • "contact_name": "Max Mustermann",
  • "contact_email": "max@monco.ai",
  • "use_case": "AI agent delegation for construction validation",
  • "industry": "construction",
  • "website": "http://example.com",
  • "lead_source": "trust-site",
  • "beta_track": "construction",
  • "asset": "home-hero"
}

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "status": "PENDING",
  • "message": "string"
}

Public widget config for embed (no auth)

Returns the public-safe widget configuration for embedding. No authentication required. Sensitive fields (secrets, internal IDs) are stripped from the response.

path Parameters
widgetId
required
string

Responses

Response samples

Content type
application/json
{
  • "widget_id": "string",
  • "tenant_name": "string",
  • "branding": { },
  • "enabled_idps": [
    ],
  • "taxonomy_libraries": [
    ]
}

SCIM

SCIM 2.0 user provisioning (Okta/Entra ID lifecycle management)

List provisioned users

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
startIndex
integer
Default: 1
count
integer
Default: 100

Responses

Response samples

Content type
application/scim+json
{ }

Provision a new user

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/scim+json
required
object

Responses

Request samples

Content type
application/scim+json
{ }

Response samples

Content type
application/scim+json
{ }

Get a provisioned user

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Replace a user

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string
Request Body schema: application/scim+json
required
object

Responses

Request samples

Content type
application/scim+json
{ }

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Partially update a user

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string
Request Body schema: application/scim+json
required
object

Responses

Request samples

Content type
application/scim+json
{ }

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Deprovision a user (revokes all mandates)

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "BAD_REQUEST",
  • "message": "principal and delegate are required"
}

Tenants

Get dashboard onboarding status

Returns the current dashboard onboarding tour status for the authenticated tenant. Used by the guided tour overlay to determine whether to show the onboarding flow.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "onboarding": {
    }
}

Update dashboard onboarding progress

Updates the dashboard onboarding tour progress for the authenticated tenant. Supports marking steps as completed, advancing the current step, and completing or skipping the entire tour.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
completed
boolean
skipped
boolean
completed_steps
Array of strings
current_step
string

Responses

Request samples

Content type
application/json
{
  • "completed": true,
  • "skipped": true,
  • "completed_steps": [
    ],
  • "current_step": "string"
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "onboarding": {
    }
}

Verification

Real-time action authorization

Verify if an action is authorized by a mandate

Performance-critical endpoint. Target: < 50ms p99 latency (without PoM), < 200ms p99 (with PoM). Returns ALLOW or DENY with optional escalation metadata and an optional Proof-of-Mandate Verifiable Credential.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
pom
string
Value: "sd-jwt-vc"

Request a Proof-of-Mandate Verifiable Credential in the response. The VC is an SD-JWT signed by the Mandaitor issuer DID.

drift
boolean
Default: false

@experimental Request drift detection signals in the response. When true, the response includes a semantic_signals object with multi-dimensional drift scoring. Drift signals are advisory only and NEVER affect the ALLOW/DENY decision. Requires the tenant to have drift detection enabled.

Request Body schema: application/json
required
delegate_subject_id
string

Canonical field. Subject ID of the delegate to verify.

agent_id
string
Deprecated

Deprecated legacy alias for delegate_subject_id. Use delegate_subject_id for new integrations.

action
required
string
resource
required
string
context
object

Additional context for constraint evaluation. When a mandate has require_mfa: true, the caller must supply MFA proof via one of:

  • amr (array of strings) — must include "mfa"
  • loa (string) — must be "SUBSTANTIAL" or "HIGH"
  • mfa_timestamp (string, ISO 8601) — timestamp of last MFA verification

Responses

Request samples

Content type
application/json
{
  • "delegate_subject_id": "monco:agent:validate-agent-v2",
  • "agent_id": "monco:agent:validate-agent-v2",
  • "action": "construction.validation.approve",
  • "resource": "monco:project:proj_ABC123/zone:EG/installation:stk_42",
  • "context": { }
}

Response samples

Content type
application/json
{
  • "decision": "ALLOW",
  • "mandate_id": "string",
  • "event_id": "string",
  • "reason_codes": [
    ],
  • "constraints_remaining": { },
  • "proof_of_mandate": {
    },
  • "proof_token": "string"
}

Playground dry-run verify (Cognito JWT, no raw API key)

Dashboard-only dry-run verify endpoint. Authenticated via Cognito JWT (dashboard session). The caller selects an API key by its key_id from a dropdown; the handler loads the key's metadata (scopes, status) and simulates the verify flow as if the request had come through that key. No raw API key is ever needed. Metering is intentionally skipped.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
key_id
required
string

API key ID to simulate (from the dropdown)

action
required
string

The action being attempted

resource
required
string

The resource being accessed

delegate_subject_id
string

The delegate attempting the action

agent_id
string

Alternative to delegate_subject_id

object

Additional context for constraint evaluation

request_pom
boolean

Whether to include a Proof-of-Mandate VC

Responses

Request samples

Content type
application/json
{
  • "key_id": "string",
  • "action": "string",
  • "resource": "string",
  • "delegate_subject_id": "string",
  • "agent_id": "string",
  • "context": { },
  • "request_pom": true
}

Response samples

Content type
application/json
{
  • "decision": "ALLOW",
  • "mandate_id": "string",
  • "event_id": "string",
  • "reason_codes": [
    ],
  • "constraints_remaining": { },
  • "proof_of_mandate": { },
  • "proof_token": "string",
  • "_playground": {
    }
}

VI Credential

Verifiable Intent (VI) compatibility layer for cross-platform credential exchange

Issue a Verifiable Intent credential chain

Generates a VI-spec compatible credential chain (L1 + L2) from an existing active mandate. The chain can be presented to external verifiers that implement the Verifiable Intent specification.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Example: mdt_01HXYZ...
Request Body schema: application/json
required
audience
required
string

Target verifier audience URI

nonce
string

Optional nonce for replay protection

agent_public_key
object

Agent's JWK public key for L2 credential

principal_public_key
object

Principal's JWK public key for L1 credential

principal_key_id
string

KMS key ID for principal signing

Responses

Request samples

Content type
application/json
{
  • "audience": "string",
  • "nonce": "string",
  • "agent_public_key": { },
  • "principal_public_key": { },
  • "principal_key_id": "string"
}

Response samples

Content type
application/json
{
  • "credential_chain": {
    },
  • "format": "vi-sd-jwt",
  • "spec_version": "1.0"
}

Widget Config

Tenant widget configuration

Get tenant widget configuration

Retrieves the widget configuration for a tenant. Returns the latest version by default, or a specific version if the version query parameter is provided.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "widget_id": "string",
  • "identity_providers": [
    ],
  • "taxonomy_libraries": [
    ],
  • "mandate_templates": [
    ],
  • "branding": {
    },
  • "approval_workflow": {
    },
  • "webhook_url": "http://example.com",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update tenant widget configuration

Updates the widget configuration for a tenant. Creates a new versioned record. IdP credentials are stored in AWS Secrets Manager.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
identity_providers
Array of objects
taxonomy_libraries
Array of strings
mandate_templates
Array of objects
branding
object
approval_workflow
object
webhook_url
string <uri>

Responses

Request samples

Content type
application/json
{
  • "identity_providers": [
    ],
  • "taxonomy_libraries": [
    ],
  • "mandate_templates": [
    ],
  • "branding": { },
  • "approval_workflow": { },
  • "webhook_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "widget_id": "string",
  • "identity_providers": [
    ],
  • "taxonomy_libraries": [
    ],
  • "mandate_templates": [
    ],
  • "branding": {
    },
  • "approval_workflow": {
    },
  • "webhook_url": "http://example.com",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Validate an IdP connection

Validates an Identity Provider configuration by attempting a client credentials flow against the specified provider (Entra ID, Auth0, Okta, or eIDAS).

Alias support: Accepts both provider (canonical) and idpType (legacy). If both are present, provider takes precedence.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
provider
string
Enum: "eidas_eudi" "entra_id" "auth0" "okta"

Canonical field. The IdP type to validate.

idpType
string
Deprecated

Deprecated legacy alias for provider.

config
required
object

Responses

Request samples

Content type
application/json
{
  • "provider": "eidas_eudi",
  • "idpType": "string",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "results": {
    }
}

List widget configuration versions

Returns a paginated list of all configuration versions for the tenant, sorted by version number descending (newest first). Each entry contains version metadata (not the full configuration body).

Authorizations:
BearerAuth
path Parameters
id
required
string
query Parameters
limit
integer <= 100
Default: 20
cursor
string

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "next_cursor": "string"
}

Rollback widget configuration to a previous version

Rolls back the widget configuration to a previous version by creating a new version that is a copy of the target version. This preserves the full version history for audit purposes — no versions are deleted.

The new version includes a rollbackFrom field indicating which version it was copied from.

Authorizations:
BearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
version
required
integer >= 1

The version number to roll back to

Responses

Request samples

Content type
application/json
{
  • "version": 1
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "version": 0,
  • "rollbackFrom": 0,
  • "widgetId": "string"
}