Verification

Test your integration

Hit verify-access with curl, see the literal response, and check it against the four common failure modes. Useful when you're standing up the merchant SDK and want to confirm everything is wired before pointing real traffic at it.

1. Happy path — verified agent

An agent registered against a counterparty endpoint with a healthy trust score. Run from a shell with your kya_* API key in env.

export ASTRA_KEY=kya_xxx...
export ASTRA_AGENT=ASTRA-yourAgentId

curl -sS -X POST https://astrasync.ai/api/agents/verify-access \
  -H "Authorization: Bearer $ASTRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'"$ASTRA_AGENT"'",
    "counterpartyUrl": "https://your-merchant.example.com/api/data",
    "counterpartyType": "api",
    "purpose": "read_data"
  }' | jq

Successful response (trimmed):

{
  "success": true,
  "data": {
    "sessionId": "vs_01J...",
    "access": {
      "allowed": true,
      "accessLevel": "standard"
    },
    "agent": {
      "astraId": "ASTRA-yourAgentId",
      "name": "Your Agent",
      "trustScore": 47,
      "agentStatus": "active",
      "blockchainStatus": "verified"
    },
    "recommendation": "grant",
    "pdlss": { "purpose": { "categories": ["read_data"] }, ... }
  }
}

2. Anonymous call (no agentId)

Drop the agentIdfrom the body. The server applies the endpoint's unverifiedAgentPolicy.

curl -sS -X POST https://astrasync.ai/api/agents/verify-access \
  -H "Authorization: Bearer $ASTRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "counterpartyUrl": "https://your-merchant.example.com/api/public",
    "counterpartyType": "api",
    "purpose": "read_data"
  }' | jq

Response when policy is allow_partial:

{
  "success": true,
  "data": {
    "sessionId": "vs_01J...",
    "access": {
      "allowed": true,
      "accessLevel": "restricted"
    },
    "agent": null,
    "advisory": {
      "ial": "unverified",
      "policy": "allow_partial",
      "registrationUrl": "https://astrasync.ai/register",
      "docsUrl": "https://astrasync.ai/docs",
      "restrictionsExplained": [
        "Without an ASTRA-id you receive restricted-level access only.",
        "Register the agent to upgrade to read-only or standard."
      ]
    },
    "recommendation": "grant"
  }
}

3. Common failure modes

Missing API key

No Authorization header.

HTTP/1.1 401 Unauthorized
{
  "error": "AUTHENTICATION_ERROR",
  "message": "No authentication token provided"
}

Fix: set Authorization: Bearer kya_xxx on the request, or pass apiKey to the SDK middleware.

Invalid API key

Bearer token doesn't resolve to an active account.

HTTP/1.1 401 Unauthorized
{
  "error": "AUTHENTICATION_ERROR",
  "message": "Invalid token"
}

Fix: regenerate the key at /dashboard/api-keys. Check you're hitting the right environment — staging keys don't work against prod and vice versa.

Anonymous call to deny-policy endpoint

No agentId, endpoint's unverifiedAgentPolicy is deny.

{
  "success": true,
  "data": {
    "access": { "allowed": false, "accessLevel": "none" },
    "agent": null,
    "advisory": {
      "ial": "unverified",
      "policy": "deny",
      "registrationUrl": "https://astrasync.ai/register",
      "restrictionsExplained": [
        "This endpoint requires a registered ASTRA-id."
      ]
    },
    "recommendation": "deny"
  }
}

Fix (caller side): register the agent at /agents/register, or step up to a recognised platform User-Agent (Claude / ChatGPT / Gemini / Cursor / Goose) which auto-provisions a provisional ASTRA-id with IAL=1.
Fix (merchant side): change the endpoint policy to allow_partial if you want anonymous traffic to receive guidance.

Trust score below route threshold

Verified agent, but live trust score is under routes[].minAccessLevel.

{
  "success": true,
  "data": {
    "access": { "allowed": true, "accessLevel": "read-only" },
    "agent": { "astraId": "ASTRA-...", "trustScore": 22, ... },
    "recommendation": "step_up_required",
    "recommendationReasons": [
      "Trust score 22 below standard tier (40+)."
    ]
  }
}

Fix:the agent should complete more trust signals (KYD, blockchain registration, agent-card publishing). The merchant's middleware will short-circuit with the onDenied handler when the route's minAccessLevelisn't met.

Purpose not allowed by PDLSS

Verified agent, but purposeisn't in the agent's permission boundary.

{
  "success": true,
  "data": {
    "access": { "allowed": false, "accessLevel": "none" },
    "agent": { "astraId": "ASTRA-...", ... },
    "recommendation": "deny",
    "denialReasons": [
      "Purpose 'execute_payment' not in PDLSS purpose.categories."
    ]
  }
}

Fix: either pass an allowed purpose (read_data, execute_action, etc.) or update the agent's PDLSS boundary at the dashboard.

apiBaseUrl missing /api

Most common config bug — pointing at the marketing site root.

AstraSync init self-test: GET https://astrasync.ai/agents/verify-access
returned content-type 'text/html'. Did you mean 'https://astrasync.ai/api'?
(Set disableInitChecks: true to silence.)

Fix: include /api in the URL. The convention is that apiBaseUrl always ends with /api — the SDK derives the registration / docs URLs by stripping it.

4. Verify your wiring

After the SDK is mounted, hit a route on your own server with curl and check the Activity dashboard. You should see:

A verification.* event in /activity > All Events within ~5s.
The endpoint's row in /activity > Endpoints shows incremented Granted / Denied / Step-up counts.
A blockchain audit record (visible on the agent's detail page after the background queue picks it up).

If nothing shows, double-check the API key is for the same account that owns the endpoint. Mismatched accounts log a agent.ownership_mismatch_attempt alert instead.