Build an AI Agent

Register an AI agent, enrich it as a governed AI asset, run governance evaluation, and track remediation through the headless AuthSpoke APIs.

This guide shows the current headless flow for an autonomous agent. The legacy Agent Directory APIs still exist under /api/v1/ai/agents; the enterprise-governed flow adds AI Registry and AI Governance APIs so the same asset can be discovered, owned, classified, evaluated, reviewed, and audited.

1. Authenticate#

export TOKEN=$(curl -s -X POST "https://your-company.authspoke.com/api/v1/auth/signin" \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"********"}' | jq -r .token)

All calls below are tenant-scoped by the token. You do not pass a tenant id or tenant subdomain in the API path.

2. Register the agent in the AI Directory#

curl -X POST "https://api.authspoke.com/api/v1/ai/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice-reconciler",
    "description": "Reconciles invoices against ERP and warehouse data.",
    "owner": "[email protected]",
    "businessUnit": "Finance",
    "modelProvider": "Anthropic",
    "modelVersion": "claude-opus-4",
    "environment": "PRODUCTION",
    "authMethod": "OAUTH",
    "lifecycleState": "REGISTERED",
    "businessCriticality": "CRITICAL",
    "productionAccess": true,
    "sensitiveDataAccess": true,
    "connectedSystems": 4,
    "connectedMcpCount": 3
  }'

AuthSpoke computes risk and trust server-side. Clients never submit those scores.

3. Register or import the governed AI Asset#

Agents discovered through a provider connector can be imported into the AI Registry. For a manual registration:

curl -X POST "https://api.authspoke.com/api/v1/ai-assets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assetName": "invoice-reconciler",
    "assetType": "AGENT",
    "providerKey": "manual",
    "environment": "PRODUCTION",
    "businessUnit": "Finance",
    "classification": "CONFIDENTIAL",
    "criticality": "CRITICAL",
    "metadata": {
      "businessPurpose": "Invoice reconciliation",
      "dataSensitivity": "CONFIDENTIAL"
    }
  }'

Capture the returned asset id as ASSET_ID.

4. Add ownership and metadata#

curl -X PATCH "https://api.authspoke.com/api/v1/ai-assets/$ASSET_ID/ownership" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerName": "[email protected]",
    "businessUnit": "Finance",
    "environment": "PRODUCTION",
    "classification": "CONFIDENTIAL",
    "criticality": "CRITICAL",
    "tags": ["finance", "production", "agent"]
  }'

curl -X PATCH "https://api.authspoke.com/api/v1/ai-assets/$ASSET_ID/metadata" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "businessPurpose": "Reconcile invoices before payment approval.",
      "dataSensitivity": "CONFIDENTIAL",
      "userPopulation": "EMPLOYEES"
    }
  }'

5. Govern lifecycle state#

curl -X PATCH "https://api.authspoke.com/api/v1/ai-assets/$ASSET_ID/lifecycle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lifecycleState":"ACTIVE","reason":"Approved for production finance workflow."}'

Lifecycle and governance changes create activity timeline events.

6. Run policy evaluation#

curl -X POST "https://api.authspoke.com/api/v1/ai-governance/evaluations/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"ASSET","assetId":"'"$ASSET_ID"'"}'

Read any findings for the asset:

curl "https://api.authspoke.com/api/v1/ai-assets/$ASSET_ID/governance-findings" \
  -H "Authorization: Bearer $TOKEN"

7. Review a finding#

curl -X POST "https://api.authspoke.com/api/v1/ai-governance/findings/$FINDING_ID/review-actions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "REQUEST_REMEDIATION",
    "reason": "Production agent needs explicit business purpose and guardrail relationship.",
    "remediationTask": {
      "taskType": "ADD_METADATA",
      "title": "Complete invoice-reconciler governance metadata",
      "description": "Add business purpose, owner, and guardrail relationship.",
      "dueAt": "2026-07-14T12:00:00Z"
    }
  }'

Available actions include START_REVIEW, APPROVE_RISK, REQUEST_REMEDIATION, CREATE_EXEMPTION, DISMISS, MARK_RESOLVED, and REOPEN.

8. Watch activity#

curl "https://api.authspoke.com/api/v1/ai-assets/$ASSET_ID/activity" \
  -H "Authorization: Bearer $TOKEN"

The same API surface supports the console, automation, MCP servers, and agents.