POST/v1/verify/challenge

Request Challenge

Request a verification challenge for an AI agent.

Description

This endpoint generates a unique challenge for verifying an AI agent's identity. The challenge contains a cryptographic nonce that the agent uses to generate a zero-knowledge proof.

Challenges expire after 5 minutes (300 seconds) and can only be used once.

Headers

Header	Value	Required
`Content-Type`	application/json	✓
`X-Api-Key`	Your API key	✓

Request Body

Parameter	Type	Required	Description
`agent_id`	string	✓	Unique identifier for the AI agent
`action`	string	✓	Action the agent intends to perform (e.g., "purchase", "refund")
`context`	object	-	Additional context about the action (optional)

Example Request

cURL

curl -X POST https://api.zeroproofai.com/v1/verify/challenge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "agent_id": "shop-bot-001",
    "action": "purchase",
    "context": {
      "item": "wireless-headphones",
      "price": 149,
      "currency": "USD"
    }
  }'

JavaScript

const response = await fetch('https://api.zeroproofai.com/v1/verify/challenge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    agent_id: 'shop-bot-001',
    action: 'purchase',
    context: {
      item: 'wireless-headphones',
      price: 149,
      currency: 'USD'
    }
  })
});

const challenge = await response.json();

Response

Success Response (200 OK)

{
  "challenge_id": "ch_7x9k2a8f3e1d9c4b",
  "nonce": "a8f3e1d9c4b7x9k2...",
  "expires_in": 300,
  "timestamp": 1704117600000
}

Field	Type	Description
`challenge_id`	string	Unique identifier for this challenge
`nonce`	string	Cryptographic nonce for proof generation
`expires_in`	number	Seconds until challenge expires (300)
`timestamp`	number	Unix timestamp in milliseconds

Error Responses

401 Unauthorized

{
  "error": "Missing API key",
  "message": "Provide API key in X-Api-Key header"
}

400 Bad Request

{
  "error": "Missing required fields: agent_id, action"
}

403 Forbidden

{
  "error": "Invalid API key"
}

Notes

Store the challenge_id and nonce for the next step
Challenges expire after 5 minutes and cannot be reused
Each successful request increments your API usage counter
The context field is stored with the challenge for reference

Next Steps

After receiving a challenge, your agent should:

Use the nonce to generate a zero-knowledge proof
Submit the proof using the Verify Proof endpoint
Include the challenge_id in the verification request