Agent Endpoints

AI agents are managed as identities with the type AI_AGENT. They include additional configuration for budget controls, token monitoring, prompt injection detection, and MCP server governance. This page covers agent-specific capabilities and the JIT request endpoints.

Agent Configuration

AI agents are created and managed through the Identity API with the type set to AI_AGENT and an agentConfig object that specifies agent-specific settings.

Agent Config Fields

Field	Type	Description
model	string	AI model identifier (e.g., gpt-4, claude-3-opus, gemini-pro)
provider	string	Model provider (e.g., openai, anthropic, google)
budgetLimit	number	Maximum spend in USD per budget period
budgetPeriod	string	Budget period: daily, weekly, monthly
maxTokensPerRequest	number	Maximum tokens allowed per individual request
promptInjectionDetection	boolean	Enable prompt injection detection (default: true)
mcpServers	string[]	Allowed MCP server identifiers for tool access
allowedTools	string[]	Allowed tool names (if MCP servers are configured)
blockedTools	string[]	Explicitly blocked tool names

Create an AI Agent

curl -X POST https://app.veraid.io/api/v1/identities \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-agent",
    "type": "AI_AGENT",
    "description": "Customer support AI agent for ticket triage and response drafting",
    "tags": ["ai-agent", "customer-support", "production"],
    "agentConfig": {
      "model": "gpt-4",
      "provider": "openai",
      "budgetLimit": 500.00,
      "budgetPeriod": "monthly",
      "maxTokensPerRequest": 4096,
      "promptInjectionDetection": true,
      "mcpServers": ["crm-server", "knowledge-base"],
      "allowedTools": [
        "crm.getTicket",
        "crm.updateTicket",
        "kb.search",
        "kb.getArticle"
      ],
      "blockedTools": [
        "crm.deleteCustomer",
        "crm.exportData"
      ]
    }
  }'

---

AI Monitoring

VeraID tracks token usage and cost for every AI agent request, providing real-time visibility into agent spending and behavior.

Usage Tracking per Request

Each API call made by an AI agent records:

Metric	Description
promptTokens	Number of tokens in the prompt/input
completionTokens	Number of tokens in the completion/output
totalTokens	Total tokens consumed
cost	Estimated cost in USD based on model pricing
model	Model used for the request
latency	Response time in milliseconds
toolCalls	Tools invoked during the request

Budget Monitoring

Query the current budget status for an AI agent:

curl -X GET https://app.veraid.io/api/v1/identities/id_agent123/budget \
  -H "Authorization: Bearer kd_live_abc123..."

Response:

{
  "identityId": "id_agent123",
  "identityName": "customer-support-agent",
  "budgetLimit": 500.00,
  "budgetPeriod": "monthly",
  "currentPeriod": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "usage": {
    "totalCost": 247.83,
    "totalTokens": 12456789,
    "requestCount": 8432,
    "averageCostPerRequest": 0.029,
    "projectedMonthlySpend": 412.72
  },
  "percentUsed": 49.6,
  "status": "OK",
  "thresholds": {
    "warning": 80,
    "critical": 95
  }
}

Budget status values:

Status	Description
OK	Usage is below the warning threshold
WARNING	Usage exceeds the warning threshold (default: 80%)
CRITICAL	Usage exceeds the critical threshold (default: 95%)
EXCEEDED	Budget limit reached; requests are blocked

Caution

When an agent’s budget status reaches EXCEEDED, all subsequent requests are blocked until the budget is increased or the next period begins. Configure alerts for WARNING and CRITICAL thresholds to avoid unexpected service disruptions.

Usage History

Query historical usage data for an AI agent:

curl -X GET "https://app.veraid.io/api/v1/identities/id_agent123/usage?period=7d&granularity=1h" \
  -H "Authorization: Bearer kd_live_abc123..."

Response:

{
  "identityId": "id_agent123",
  "period": "7d",
  "granularity": "1h",
  "dataPoints": [
    {
      "timestamp": "2026-03-19T09:00:00Z",
      "cost": 12.45,
      "tokens": 623400,
      "requests": 412
    },
    {
      "timestamp": "2026-03-19T10:00:00Z",
      "cost": 15.22,
      "tokens": 761000,
      "requests": 503
    }
  ],
  "summary": {
    "totalCost": 247.83,
    "totalTokens": 12456789,
    "totalRequests": 8432,
    "peakHourlyCost": 28.91,
    "peakHourlyRequests": 892
  }
}

---

JIT Request Endpoints

Just-in-time (JIT) access requests allow agents and other identities to request temporary elevated permissions with human approval.

List JIT Requests

GET /api/v1/jit-requests

Query Parameters

Parameter	Type	Description
status	string	Filter by status: PENDING, APPROVED, DENIED, EXPIRED
identityId	string	Filter by requesting identity
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)

Example Request

curl -X GET "https://app.veraid.io/api/v1/jit-requests?status=PENDING" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "jit_abc123",
      "identityId": "id_agent456",
      "identityName": "customer-support-agent",
      "status": "PENDING",
      "requestedScopes": ["crm.writeTicket", "crm.escalate"],
      "duration": "2h",
      "justification": "Customer escalation requires write access to update ticket priority and assign to tier-2 support",
      "requestedAt": "2026-03-19T10:15:00Z",
      "expiresAt": null,
      "approver": null,
      "approvedAt": null,
      "metadata": {
        "ticketId": "TICKET-4521",
        "customerId": "cust_xyz"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Create JIT Request

POST /api/v1/jit-requests

Request Body

Field	Type	Required	Description
identityId	string	Yes	Identity requesting elevated access
scopes	string[]	Yes	Scopes being requested
duration	string	Yes	Requested duration (e.g., 30m, 2h, 1d)
justification	string	Yes	Reason for the access request
metadata	object	No	Additional context (ticket ID, incident reference, etc.)

Example Request

curl -X POST https://app.veraid.io/api/v1/jit-requests \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "id_agent456",
    "scopes": ["crm.writeTicket", "crm.escalate"],
    "duration": "2h",
    "justification": "Customer escalation requires write access to update ticket priority and assign to tier-2 support",
    "metadata": {
      "ticketId": "TICKET-4521",
      "customerId": "cust_xyz"
    }
  }'

Example Response

{
  "id": "jit_def789",
  "identityId": "id_agent456",
  "identityName": "customer-support-agent",
  "status": "PENDING",
  "requestedScopes": ["crm.writeTicket", "crm.escalate"],
  "duration": "2h",
  "justification": "Customer escalation requires write access to update ticket priority and assign to tier-2 support",
  "requestedAt": "2026-03-19T10:30:00Z",
  "notificationsSent": ["slack:#access-approvals", "email:security-team@company.com"],
  "metadata": {
    "ticketId": "TICKET-4521",
    "customerId": "cust_xyz"
  }
}

Get JIT Request

GET /api/v1/jit-requests/{id}

Example Request

curl -X GET https://app.veraid.io/api/v1/jit-requests/jit_def789 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "id": "jit_def789",
  "identityId": "id_agent456",
  "identityName": "customer-support-agent",
  "status": "APPROVED",
  "requestedScopes": ["crm.writeTicket", "crm.escalate"],
  "duration": "2h",
  "justification": "Customer escalation requires write access to update ticket priority and assign to tier-2 support",
  "requestedAt": "2026-03-19T10:30:00Z",
  "approver": {
    "id": "usr_admin001",
    "name": "Bob Smith",
    "email": "bob@company.com"
  },
  "approvedAt": "2026-03-19T10:32:00Z",
  "credential": {
    "id": "cred_jit_abc",
    "expiresAt": "2026-03-19T12:32:00Z"
  },
  "expiresAt": "2026-03-19T12:32:00Z",
  "metadata": {
    "ticketId": "TICKET-4521",
    "customerId": "cust_xyz"
  }
}

Tip

Configure auto-approval rules for low-risk JIT requests to reduce approval latency. For example, requests for read-only scopes from identities with a risk score below 30 can be auto-approved during business hours.