> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller Authentication

> Verify caller identity using PIN, date of birth, passphrase, or custom credentials before proceeding with sensitive operations.

# Caller Authentication

The **Caller Authentication** tool requires callers to verify their identity before the agent processes any request. The agent prompts for a credential (PIN, date of birth, passphrase, or custom) and tracks attempts with configurable failure actions.

## How It Works

```
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?"
```

If the caller fails:

```
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
```

## Configuration

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

| Setting                    | Type    | Default        | Description                                         |
| -------------------------- | ------- | -------------- | --------------------------------------------------- |
| `callerAuthEnabled`        | boolean | `false`        | Enable caller authentication                        |
| `callerAuthType`           | string  | `pin`          | Auth type: `pin`, `dob`, `passphrase`, `custom`     |
| `callerAuthPrompt`         | string  | auto-generated | Custom authentication prompt                        |
| `callerAuthMaxAttempts`    | integer | `3`            | Maximum verification attempts                       |
| `callerAuthFailAction`     | string  | `end_call`     | On max failures: `end_call`, `transfer`, `continue` |
| `callerAuthTransferTarget` | string  | —              | Phone number for transfer on failure                |

## Auth Types

| Type         | What the Agent Asks                                          |
| ------------ | ------------------------------------------------------------ |
| `pin`        | "Please provide your PIN code to verify your identity."      |
| `dob`        | "Please provide your date of birth to verify your identity." |
| `passphrase` | "Please provide your passphrase to verify your identity."    |
| `custom`     | Uses your custom `callerAuthPrompt`                          |

## LLM Tools

### `verify_caller_identity`

Called when the caller provides a correct credential.

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

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

### `fail_caller_auth`

Called when the caller's credential is incorrect.

```
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
```

## Failure Actions

| Action     | Behavior                                                      |
| ---------- | ------------------------------------------------------------- |
| `end_call` | Agent says goodbye and hangs up                               |
| `transfer` | Agent transfers to the configured phone number                |
| `continue` | Agent continues with limited access (no sensitive operations) |

## Example — Create Agent with PIN Authentication

```bash theme={null}
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"
  }'
```

## Webhook Events

Authentication attempts fire webhook events:

```json theme={null}
// 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" }
```