> ## 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.

# List BYOK Providers

> List all supported BYOK (Bring Your Own Key) providers

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://api.thinnest.ai/byok/providers \
    -H "Authorization: Bearer $THINNESTAI_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.thinnest.ai/byok/providers"
  headers = {
      "Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.thinnest.ai/byok/providers", {
    method: "GET",
    headers: {
      "Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://api.thinnest.ai/byok/providers", nil)
      req.Header.Set("Authorization", "Bearer YOUR_THINNESTAI_API_KEY")

      resp, err := http.DefaultClient.Do(req)
      if err != nil { panic(err) }
      defer resp.Body.Close()
      body, _ := io.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</RequestExample>

## List BYOK Providers

Returns all supported LLM, STT, TTS, and Phone providers that accept BYOK API keys.

### Request

```
GET /byok/providers
```

No authentication required.

### Response

<ResponseExample>
  ```json 200 theme={null}
  {
    "providers": [
      {
        "provider": "openai",
        "name": "OpenAI",
        "type": "llm",
        "description": "GPT-4o, GPT-4o-mini, o1, o3, o4",
        "docs_url": "https://platform.openai.com/api-keys",
        "key_prefix": "sk-",
        "logo": "/logos/OpenAI.png"
      },
      {
        "provider": "anthropic",
        "name": "Anthropic",
        "type": "llm",
        "description": "Claude 4, Claude 3.5 Sonnet, Claude 3 Opus/Haiku",
        "docs_url": "https://console.anthropic.com/settings/keys",
        "key_prefix": "sk-ant-",
        "logo": "/logos/anthropic.png"
      }
    ]
  }
  ```
</ResponseExample>

### Supported Providers

| Provider                                  | Type    | Models / Use                                                                                             |
| ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `openai`                                  | LLM     | GPT-4o, GPT-4o-mini, o1, o3                                                                              |
| `anthropic`                               | LLM     | Claude 4, Claude 3.5 Sonnet                                                                              |
| `google`                                  | LLM     | Gemini 2.5, 2.0 Flash, 1.5 Pro                                                                           |
| `groq`                                    | LLM     | Llama, Qwen, GPT-OSS, Kimi K2                                                                            |
| `mistral`                                 | LLM     | Mistral Large, Codestral                                                                                 |
| `deepseek`                                | LLM     | DeepSeek V3, R1                                                                                          |
| `cohere`                                  | LLM     | Command R+, Command R                                                                                    |
| `xai`                                     | LLM     | Grok-2, Grok-3                                                                                           |
| `perplexity`                              | LLM     | Sonar Large/Small                                                                                        |
| `together`                                | LLM     | 100+ open models                                                                                         |
| `deepgram`                                | STT     | Nova-3, Nova-2, Aura TTS                                                                                 |
| `assemblyai`                              | STT     | Universal-3 Pro                                                                                          |
| `cartesia`                                | TTS     | Sonic-3, Ink Whisper STT                                                                                 |
| `elevenlabs`                              | TTS     | Turbo v2.5, Scribe STT                                                                                   |
| `sarvam`                                  | STT/TTS | Saarika/Saaras STT, Bulbul v2/v3 TTS                                                                     |
| `rime`                                    | TTS     | Mist                                                                                                     |
| `google_cloud`                            | STT     | Chirp, Studio TTS                                                                                        |
| `vobiz`                                   | Phone   | Import your own Vobiz Indian DID numbers                                                                 |
| `twilio`                                  | Phone   | Import your own Twilio phone numbers                                                                     |
| `plivo`                                   | Phone   | Import your own Plivo numbers (per-phone webhook signature uses your auth token)                         |
| `exotel`                                  | Phone   | Import your own Exotel numbers (per-phone webhook uses IP allowlist + token)                             |
| `telnyx`                                  | Phone   | Import your own Telnyx numbers — webhook signatures verified via your portal-exported Ed25519 public key |
| `razorpay_key_id` + `razorpay_key_secret` | Tool    | Per-tenant Razorpay merchant credentials for the **UPI Payment** voice tool                              |
| `surepass`                                | Tool    | Per-tenant Surepass API key for the **Aadhaar eKYC** voice tool                                          |

### Phone Provider BYOK

Phone providers require **two credentials** (stored as a JSON string):

**Vobiz:**

```json theme={null}
{
  "auth_id": "your_vobiz_auth_id",
  "auth_token": "your_vobiz_auth_token"
}
```

**Twilio:**

```json theme={null}
{
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auth_token": "your_twilio_auth_token"
}
```

**Plivo:**

```json theme={null}
{
  "auth_id": "your_plivo_auth_id",
  "auth_token": "your_plivo_auth_token"
}
```

The `auth_token` is reused at runtime to verify `X-Plivo-Signature-V3`
on inbound `/plivo/incoming/{phone_id}` and `/plivo/status/{phone_id}`
webhooks (HMAC-SHA256 over `url + nonce + body`).

**Exotel:**

```json theme={null}
{
  "api_key": "...",
  "api_token": "...",
  "account_sid": "...",
  "subdomain": "api.exotel.com"
}
```

Exotel doesn't sign webhooks — instead the `/exotel/incoming/{phone_id}`
and `/exotel/status/{phone_id}` endpoints fail closed unless the request
comes from an IP in the `EXOTEL_ALLOWED_IPS` env (default: built-in
allowlist of current AP-South-1 + US-West-2 callback IPs). Optionally
add a per-phone token to the URL as a `?token=…` query param and store
it as `phone_numbers.config.exotel_webhook_token`.

**Telnyx:**

```json theme={null}
{
  "api_key": "your_telnyx_api_key",
  "public_key": "<base64 Ed25519 public key from Portal → Webhooks → Public Keys>"
}
```

The `public_key` is REQUIRED if you want inbound webhook signature
verification — `/webhooks/telnyx/voice` rejects unsigned POSTs (pre-fix
they were accepted, which let any internet attacker dispatch a
billable agent on `call.initiated`). Rotates \~annually from the Telnyx
portal.

Use the dedicated BYOK endpoints for phone providers:

* `POST /voice/vobiz/byok/validate` — Validate Vobiz credentials and list numbers
* `POST /voice/vobiz/byok/import` — Import a Vobiz number
* `POST /voice/twilio/byok/validate` — Validate Twilio credentials and list numbers
* `POST /voice/twilio/byok/import` — Import a Twilio number
* `POST /voice/plivo/byok/validate` — Validate Plivo credentials and list numbers
* `POST /voice/plivo/byok/import` — Import a Plivo number
* `POST /voice/exotel/byok/validate` — Validate Exotel credentials and list numbers
* `POST /voice/exotel/byok/import` — Import an Exotel number
* `POST /voice/telnyx/byok/validate` — Validate Telnyx credentials and list numbers
* `POST /voice/telnyx/byok/import` — Import a Telnyx number

Phone BYOK numbers have `billing_status: "byok"` and `monthly_cost_cents: 0`. You pay your phone provider directly — thinnestAI only charges for AI agent processing minutes.

### Tool Provider BYOK (UPI Payment, Aadhaar eKYC)

Some voice tools are per-tenant: each agent owner brings their own
merchant / KYC account so the platform never holds custody of the
underlying credentials.

**UPI Payment** — uses Razorpay. Set both keys with `POST /byok/set`:

```bash theme={null}
curl -X POST https://api.thinnest.ai/byok/set \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "razorpay_key_id",
    "key": "rzp_live_..."
  }'
curl -X POST https://api.thinnest.ai/byok/set \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "razorpay_key_secret",
    "key": "..."
  }'
```

**Aadhaar eKYC** — uses Surepass:

```bash theme={null}
curl -X POST https://api.thinnest.ai/byok/set \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "surepass",
    "key": "your_surepass_api_key"
  }'
```

Without these keys saved, the corresponding tools refuse to load and
the agent surfaces "tool not configured" instead of falling back to
platform credentials.


## OpenAPI

````yaml GET /byok/providers
openapi: 3.1.0
info:
  title: ThinnestAI API
  description: REST API for ThinnestAI — build, deploy, and manage AI agents.
  version: 1.0.0
servers: []
security: []
tags:
  - name: Agents
    description: Create, configure, and manage AI agents
  - name: Chat
    description: Send messages and get AI responses from agents
  - name: Knowledge
    description: Upload files, URLs, and text to agent knowledge bases
  - name: Sessions
    description: View and manage chat sessions and message history
  - name: Voice
    description: Start and manage voice call sessions
  - name: Recordings
    description: Manage voice call recordings
  - name: Campaigns
    description: Create and run automated outreach campaigns
  - name: Webhooks
    description: Register webhook endpoints for real-time event notifications
  - name: Evaluations
    description: Run and track agent evaluation benchmarks
  - name: Analytics
    description: Query agent performance metrics and usage data
  - name: Agent Tools
    description: View and manage tools attached to agents
  - name: BYOK
    description: >-
      Bring Your Own Key — manage credentials for LLM/STT/TTS providers,
      telephony BYOK (Vobiz/Twilio/Plivo/Exotel/Telnyx), and tool-specific BYOK
      (Razorpay UPI Payment, Surepass Aadhaar eKYC)
paths:
  /byok/providers:
    get:
      tags:
        - BYOK
      summary: List Byok Providers
      description: List all supported BYOK providers with metadata.
      operationId: list_byok_providers_byok_providers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}

````