Agent: "Before I can help you, I need to verify your identity. What is your 4-digit PIN?"
Caller: "1234"
-> Agent calls verify_caller_identity with response "1234"
Agent: "Thank you, you've been verified. How can I help you today?"

Agent: "I'm sorry, that PIN is incorrect. You have 2 attempts remaining."
Caller: "5678"
-> Agent calls fail_caller_auth
Agent: "That's also incorrect. You have 1 attempt remaining."
Caller: "0000"
-> Agent calls fail_caller_auth (max attempts exceeded)
-> fail_action triggers: end_call, transfer, or continue with limited access

{
  "callerAuthEnabled": true,
  "callerAuthType": "pin",
  "callerAuthPrompt": "Please provide your 4-digit security PIN.",
  "callerAuthMaxAttempts": 3,
  "callerAuthFailAction": "end_call",
  "callerAuthTransferTarget": "+14155551234"
}

Parameters:
  response: string (the caller's authentication response)

Returns: "Caller identity verified successfully. You may now proceed with their request."

Parameters:
  reason: string (why authentication failed)

Returns: "Authentication failed. The caller has {N} attempt(s) remaining."
  or on max attempts: triggers the configured fail_action

curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure Account Agent",
    "model": "gpt-4o",
    "instructions": "You help customers with account inquiries. Caller must verify their identity before you process any request.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "callerAuthEnabled": true,
    "callerAuthType": "pin",
    "callerAuthPrompt": "Please provide your 4-digit security PIN.",
    "callerAuthMaxAttempts": 3,
    "callerAuthFailAction": "end_call"
  }'

// On attempt
{ "event": "caller.auth_attempt", "attempt": 1, "max_attempts": 3, "auth_type": "pin" }

// On success
{ "event": "caller.authenticated", "auth_type": "pin", "attempts_used": 1 }

// On failure
{ "event": "caller.auth_failed", "attempt": 2, "max_attempts": 3, "reason": "Incorrect PIN" }