Endpoint Verification

Control which external APIs your agents can call. Whitelist endpoints, approve requests, and verify TLS certificates.

Overview

When an agent calls authorize() with an endpoint_url, Aira checks it against your organization's endpoint whitelist. Unrecognized endpoints are blocked at authorization time, before the agent ever executes. An approval request is created for an admin to review.

How It Works

Agent calls authorize() with endpoint_url.
Aira checks the URL against the org's whitelist.
Whitelisted. Authorization proceeds normally.
Not whitelisted (strict mode). authorize() raises ENDPOINT_NOT_WHITELISTED with a 403. The agent must not execute. An approval request is created.
Not whitelisted (permissive mode). Authorization returns with a warning flag.
Admin reviews and approves or rejects the endpoint in the dashboard.

Endpoints

List Whitelist

GET /api/v1/endpoint-whitelist

Auth required. Returns all whitelisted URL patterns for the organization.

{
  "entries": [
    {
      "id": "ewl_abc123",
      "url_pattern": "https://api.stripe.com/*",
      "name": "Stripe API",
      "status": "approved",
      "created_by": "user_xyz",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ]
}

Add to Whitelist

POST /api/v1/endpoint-whitelist

Auth required. Admin/owner entries are auto-approved. Member entries require admin approval.

{
  "url_pattern": "https://api.stripe.com/*",
  "name": "Stripe API"
}

Response:

{
  "id": "ewl_abc123",
  "url_pattern": "https://api.stripe.com/*",
  "name": "Stripe API",
  "status": "approved",
  "created_at": "2026-03-15T10:30:00Z"
}

Approve Whitelist Entry

POST /api/v1/endpoint-whitelist/{id}/approve

Admin required. Approves a pending whitelist entry.

Reject Whitelist Entry

POST /api/v1/endpoint-whitelist/{id}/reject

Admin required. Rejects a pending whitelist entry.

Delete Whitelist Entry

DELETE /api/v1/endpoint-whitelist/{id}

Admin required. Removes an endpoint from the whitelist.

List Pending Approvals

GET /api/v1/endpoint-approvals

Auth required. Returns blocked actions waiting for admin review.

{
  "approvals": [
    {
      "id": "eap_def456",
      "url": "https://api.newservice.com/v1/send",
      "agent_id": "support-agent",
      "url_pattern_suggested": "https://api.newservice.com/*",
      "requested_at": "2026-03-20T14:22:00Z"
    }
  ]
}

Approve Approval Request

POST /api/v1/endpoint-approvals/{id}/approve

Admin required. Approves the blocked action and optionally adds the suggested URL pattern to the whitelist.

Reject Approval Request

POST /api/v1/endpoint-approvals/{id}/reject

Admin required. Rejects the blocked action request.

SDK Usage

Authorize with endpoint_url

Pass endpoint_url on the authorize() call. The endpoint is checked as part of policy evaluation.

from aira import Aira

aira = Aira(api_key="aira_live_...")

auth = aira.authorize(
    action_type="api_call",
    details="Charge customer 49.99 USD for subscription renewal",
    agent_id="billing-agent",
    model_id="claude-sonnet-4-6",
    endpoint_url="https://api.stripe.com/v1/charges",
)

if auth.status == "authorized":
    result = stripe.Charge.create(amount=4999, currency="usd")
    aira.notarize(
        action_uuid=auth.action_uuid,
        outcome="completed",
        outcome_details=f"Charged. stripe_id={result.id}",
    )

import { Aira } from "aira-sdk";

const aira = new Aira({ apiKey: "aira_live_..." });

const auth = await aira.authorize({
  actionType: "api_call",
  details: "Charge customer 49.99 USD for subscription renewal",
  agentId: "billing-agent",
  modelId: "claude-sonnet-4-6",
  endpointUrl: "https://api.stripe.com/v1/charges",
});

if (auth.status === "authorized") {
  const result = await stripe.charges.create({ amount: 4999, currency: "usd" });
  await aira.notarize({
    actionId: auth.action_uuid,
    outcome: "completed",
    outcomeDetails: `Charged. stripe_id=${result.id}`,
  });
}

Handle blocked action

When an endpoint is not whitelisted and the org is in strict mode, the authorize() call raises ENDPOINT_NOT_WHITELISTED. The agent must not execute and there is nothing to notarize.

from aira import Aira, AiraError

aira = Aira(api_key="aira_live_...")

try:
    auth = aira.authorize(
        action_type="api_call",
        details="Send SMS via new provider",
        agent_id="notifications-agent",
        endpoint_url="https://api.newprovider.com/v1/sms",
    )
except AiraError as e:
    if e.code == "ENDPOINT_NOT_WHITELISTED":
        print(f"Blocked: {e.message}")
        print(f"Approval request created: {e.details['approval_id']}")
        print(f"Suggested pattern: {e.details['url_pattern_suggested']}")
    else:
        raise

import { Aira, AiraError } from "aira-sdk";

const aira = new Aira({ apiKey: "aira_live_..." });

try {
  const auth = await aira.authorize({
    actionType: "api_call",
    details: "Send SMS via new provider",
    agentId: "notifications-agent",
    endpointUrl: "https://api.newprovider.com/v1/sms",
  });
} catch (e) {
  if (e instanceof AiraError && e.code === "ENDPOINT_NOT_WHITELISTED") {
    console.log(`Blocked: ${e.message}`);
    console.log(`Approval request created: ${e.details.approval_id}`);
    console.log(`Suggested pattern: ${e.details.url_pattern_suggested}`);
  } else {
    throw e;
  }
}

Manage whitelist programmatically

from aira import Aira

aira = Aira(api_key="aira_live_xxx")

# List current whitelist
entries = aira.list_endpoint_whitelist()

# Add a new endpoint pattern
entry = aira.add_endpoint_whitelist(
    url_pattern="https://api.twilio.com/*",
    name="Twilio API",
)

# List pending approval requests
approvals = aira.list_endpoint_approvals()

# Approve a pending request (admin only)
aira.approve_endpoint(approval_id="eap_def456")

# Delete a whitelist entry (admin only)
aira.delete_endpoint_whitelist(entry_id="ewl_abc123")

import { Aira } from "aira-sdk";

const aira = new Aira({ apiKey: "aira_live_xxx" });

// List current whitelist
const entries = await aira.listEndpointWhitelist();

// Add a new endpoint pattern
const entry = await aira.addEndpointWhitelist({
  urlPattern: "https://api.twilio.com/*",
  name: "Twilio API",
});

// List pending approval requests
const approvals = await aira.listEndpointApprovals();

// Approve a pending request (admin only)
await aira.approveEndpoint({ approvalId: "eap_def456" });

// Delete a whitelist entry (admin only)
await aira.deleteEndpointWhitelist({ entryId: "ewl_abc123" });

cURL Examples

# List whitelist
curl -H "Authorization: Bearer aira_live_xxx" \
  https://api.airaproof.com/api/v1/endpoint-whitelist

# Add to whitelist
curl -X POST -H "Authorization: Bearer aira_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url_pattern": "https://api.stripe.com/*", "name": "Stripe API"}' \
  https://api.airaproof.com/api/v1/endpoint-whitelist

# List pending approvals
curl -H "Authorization: Bearer aira_live_xxx" \
  https://api.airaproof.com/api/v1/endpoint-approvals

# Approve a pending request
curl -X POST -H "Authorization: Bearer aira_live_xxx" \
  https://api.airaproof.com/api/v1/endpoint-approvals/eap_def456/approve

# Delete a whitelist entry
curl -X DELETE -H "Authorization: Bearer aira_live_xxx" \
  https://api.airaproof.com/api/v1/endpoint-whitelist/ewl_abc123

Endpoint Verification

On this page