Proquiro Agent Authentication Guide

Authentication model at a glance

Because the public surface is unauthenticated, agents do not need to obtain an API key for the resources documented at /developers. Identification is done via headers and IP-based rate limiting.

Step 1 — Identify your agent

Send a descriptive User-Agent on every request. Include the agent name, version, and a contact URL or email so we can reach you about abuse, policy issues, or quota uplift requests. This is the single most important authentication signal for unauthenticated requests.

User-Agent: AcmeAgent/1.4 (+https://acme.example/agents)

Generic User-Agents (curl, python-requests, headless-browser defaults) are rate-limited more aggressively and may be blocked entirely if abusive.

Step 2 — Calling unauthenticated endpoints

No tokens are needed. Send a JSON body with Content-Type: application/json and read structured JSON errors back. All errors include a stable error.code, a human error.message, an optional error.hint, and a error.docs URL.

curl -sS https://proquiro.com/api/demo-request \
  -H 'User-Agent: AcmeAgent/1.4 (+https://acme.example/agents)' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane@company.com",
    "phone": "+91 99000 00000"
  }'

Successful responses return 200 with application/json. Failures use the appropriate HTTP status code (400, 409, 429, 500) with this shape:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests from this network. Please try again later.",
    "hint": "Limit: 5 requests per IP per hour.",
    "docs": "https://proquiro.com/developers#proquiro-public-api"
  }
}

On 429 RATE_LIMITED, the Retry-After header indicates how long to wait before retrying. Honor it.

Step 3 — Connecting an MCP client

The Proquiro MCP server uses the Streamable HTTP transport at POST https://proquiro.com/mcp. No bearer token is required. Sessions are identified by an Mcp-Session-Id header that the server issues on the first response — pass it back on subsequent requests to keep a session alive.

Capability handshake (initialize) example:

curl -sS https://proquiro.com/mcp \
  -H 'User-Agent: AcmeAgent/1.4 (+https://acme.example/agents)' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "AcmeAgent", "version": "1.4" }
    }
  }' -i

The response carries Mcp-Session-Id and Mcp-Protocol-Version headers. If you set Accept: text/event-stream, replies are streamed as SSE; otherwise they come back as JSON.

For the full server card (transport, capabilities, tools), fetch /.well-known/mcp/server-card.json.

Step 4 — Higher-volume access (partner program)

For agent platforms, integrators, and ISVs that need higher rate limits, authenticated hosted-app data access, or co-development on agent workflows, contact the Proquiro team:

• Email info@proquiro.com with subject "Partner API access — <your platform>"
• Include: agent name, expected request volume, target endpoints, identifying User-Agent, and a contact URL
• We issue Bearer tokens scoped to specific endpoints and quotas. Tokens are passed as Authorization: Bearer <token> on every request and rotated on request

Partner tokens are not available via self-service signup today. This is by design — it keeps the public surface low-noise while we onboard integrations one at a time.

Operational guardrails for agents

• Idempotency: the lead-capture endpoints dedupe on email + tool slug. Repeated submissions return 409 DUPLICATE_REQUEST rather than inserting duplicates
• Honeypot: the website field must be empty. Submitting any value triggers 400 HONEYPOT_TRIGGERED
• Disposable email rejection: mailinator-class domains are rejected with 400 DISPOSABLE_EMAIL
• CORS: all Proquiro public endpoints set Access-Control-Allow-Origin: *, so browser-resident agents can call them
• HTTPS-only: every endpoint is served over TLS. HTTP requests are redirected

See also: Proquiro AI Policy, Privacy Policy, and Terms / MSA.