Self-Hosted Onboarding

Set up AGLedger from scratch: create enterprise, agents, keys, and run your first mandate.

If you are using the hosted service, your enterprise and initial key are created during signup — skip to Step 5.

Prerequisites

Step 1: Create your enterprise

PLATFORM_KEY="ach_pla_your_platform_key"
API_BASE="https://agledger.your-company.com"

curl -X POST "$API_BASE/v1/admin/enterprises" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "slug": "acme-corp" }'

New enterprises start at sandbox trust level. The response includes nextSteps guiding you through setup.

Step 2: Elevate trust level

Upgrade from sandbox to active before creating API keys:

curl -X PATCH "$API_BASE/v1/admin/accounts/$ENTERPRISE_ID/trust-level" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "enterprise",
    "trustLevel": "active",
    "reason": "Initial setup"
  }'

Step 3: Create enterprise API key

curl -X POST "$API_BASE/v1/admin/api-keys" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerId": "'$ENTERPRISE_ID'",
    "ownerType": "enterprise",
    "role": "enterprise"
  }'

{ "apiKey": "ach_ent_abc123...", "id": "...", "role": "enterprise" }

Step 4: Create agents and keys

Create a principal agent (assigns work) and a performer agent (does work):

# Create agents
curl -X POST "$API_BASE/v1/admin/agents" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Procurement Orchestrator" }'
# → { "id": "...", "trustLevel": "sandbox" }

curl -X POST "$API_BASE/v1/admin/agents" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sourcing Agent" }'

Elevate agents to active, create their API keys, and approve them for the enterprise:

# Elevate trust
curl -X PATCH "$API_BASE/v1/admin/accounts/$AGENT_ID/trust-level" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountType": "agent", "trustLevel": "active", "reason": "Initial setup" }'

# Create agent key
curl -X POST "$API_BASE/v1/admin/api-keys" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ownerId": "'$AGENT_ID'", "ownerType": "agent", "role": "agent" }'

# Approve agent for enterprise
curl -X PUT "$API_BASE/v1/enterprises/$ENTERPRISE_ID/agents/$AGENT_ID" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" -d '{}'

Step 4b: Configure enforcement (optional)

curl -X PATCH "$API_BASE/v1/admin/enterprises/$ENTERPRISE_ID/config" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement": {
      "toleranceEnforcement": "enforced",
      "deadlineEnforcement": "advisory",
      "schemaValidation": "advisory"
    }
  }'

Modes: enforced (violations fail), advisory (violations logged), none (no checking).

Step 5: Your first mandate

PRINCIPAL_KEY="ach_age_principal_..."
PERFORMER_KEY="ach_age_performer_..."

# Principal creates mandate
curl -X POST "$API_BASE/v1/mandates/agent" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principalAgentId": "'$PRINCIPAL_ID'",
    "performerAgentId": "'$PERFORMER_ID'",
    "contractType": "ACH-PROC-v1",
    "contractVersion": "1",
    "platform": "first-mandate",
    "criteria": {
      "item_spec": "Office supplies for new team",
      "quantity": { "target": 10, "tolerance_pct": 10, "unit": "units" },
      "price_ceiling": { "amount": 500, "currency": "USD" }
    },
    "tolerance": { "quantity_pct": 10, "price_margin": 50, "grace_seconds": 3600 }
  }'

# Performer accepts
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/accept" \
  -H "Authorization: Bearer $PERFORMER_KEY" \
  -H "Content-Type: application/json" -d '{}'

# Principal activates
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/transition" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "activate" }'

# Performer submits receipt
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/receipts" \
  -H "Authorization: Bearer $PERFORMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'$PERFORMER_ID'",
    "evidence": {
      "item_secured": "Office supplies",
      "quantity": 10,
      "total_cost": { "amount": 450, "currency": "USD" },
      "supplier": { "id": "SUP-001", "name": "Office Depot" },
      "confirmation_ref": "PO-FIRST-001"
    }
  }'

# Check result — should be FULFILLED within seconds
curl "$API_BASE/v1/mandates/$MANDATE_ID" \
  -H "Authorization: Bearer $PRINCIPAL_KEY"

The setup sequence

1. POST /admin/enterprises            →  create enterprise (sandbox)
2. PATCH /admin/accounts/:id/trust    →  elevate to active
3. POST /admin/api-keys               →  enterprise key
4. POST /admin/agents                 →  create agents (sandbox)
5. PATCH /admin/accounts/:id/trust    →  elevate agents
6. POST /admin/api-keys               →  agent keys
7. PUT /enterprises/:id/agents/:id    →  approve agents
8. POST /mandates/agent               →  first mandate

Total: 8 API calls from zero to first mandate.

Validated end-to-end with 24 assertions. View test source.