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

# SIP Credentials and Trunk Configuration

> Configure SIP trunk credentials for connecting to any VoIP provider. Set up authentication, transport protocols, and rate limiting.

Configure SIP credentials to connect your organization to any VoIP provider. Credentials are shared across your organization — create them once, then link phone numbers to use them.

**What you'll learn:** How to configure SIP credentials, choose transport protocols, set up rate limiting, and troubleshoot connection issues.

***

## SIP credentials overview

SIP credentials store the authentication details for your SIP trunk provider. Create credentials once at the organization level, then link multiple phone numbers to use them.

***

## Create SIP credentials

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers** → **Credentials** tab
    2. Click **Add Credentials**
    3. Fill in the configuration fields
    4. Click **Save**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-credentials', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        server: 'sip.provider.com:5060',
        authUser: 'your-username',
        authPassword: 'your-password',
        domain: 'sip.provider.com',
        transport: 'udp',
        description: 'Production Trunk'
      })
    });

    const credentials = await response.json();
    ```
  </Tab>
</Tabs>

***

## Configuration fields

### Required

| Field    | Format          | Description                                                      |
| -------- | --------------- | ---------------------------------------------------------------- |
| `server` | `hostname:port` | SIP server address. Include port if non-standard (default: 5060) |

### Authentication

| Field          | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `authUser`     | Username for SIP authentication (provided by your provider)         |
| `authPassword` | Password for SIP authentication                                     |
| `domain`       | SIP domain/realm for authentication (often same as server hostname) |

### Transport

| Field       | Values              | Description                                 |
| ----------- | ------------------- | ------------------------------------------- |
| `transport` | `udp`, `tcp`, `tls` | Protocol for SIP signaling (default: `udp`) |

### Rate limiting

| Field      | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| `cpsLimit` | Maximum calls per second through this trunk                   |
| `cpsKey`   | Shared key to combine rate limits across multiple credentials |

***

## Transport protocols

Choose the right transport based on your requirements:

| Protocol | Port | Encryption | Use when                         |
| -------- | ---- | ---------- | -------------------------------- |
| **UDP**  | 5060 | No         | Standard setup, lowest latency   |
| **TCP**  | 5060 | No         | Behind restrictive firewalls     |
| **TLS**  | 5061 | Yes        | Security/compliance requirements |

<Accordion title="Example: TLS configuration">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    server: 'sip.provider.com:5061',
    authUser: 'your-username',
    authPassword: 'your-password',
    transport: 'tls'
  }
  ```
</Accordion>

***

## Rate limiting

Control call pacing to avoid exceeding your provider's limits.

### Single trunk limit

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  server: 'sip.provider.com',
  authUser: 'trunk-1',
  cpsLimit: 10  // Max 10 calls/second
}
```

### Shared limit across trunks

When you have multiple trunks with a shared rate limit from your provider:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Trunk 1
{
  server: 'sip.provider.com',
  authUser: 'trunk-1',
  cpsLimit: 20,
  cpsKey: 'provider-shared'  // Share limit with trunk-2
}

// Trunk 2
{
  server: 'sip.provider.com',
  authUser: 'trunk-2',
  cpsLimit: 20,
  cpsKey: 'provider-shared'  // Combined limit: 20 CPS total
}
```

***

## Provider-managed credentials

When you connect a Twilio provider, SIP credentials are created automatically:

* **Source**: Shows as `provider` instead of `manual`
* **Read-only**: Cannot modify provider-managed credentials
* **Lifecycle**: Deleted when the provider is deleted

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Response shows source type
{
  id: 'cred-123',
  source: 'provider',      // Created by Twilio integration
  providerId: 'prov-456',  // Reference to Twilio provider
  server: 'sip.twilio.com'
  // ... other fields
}
```

***

## Check credential usage

Before modifying or deleting credentials, check which phone numbers and agents depend on them:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const affected = await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}/affected-agents`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log('Phone numbers using these credentials:');
affected.phoneNumbers.forEach(pn => {
  console.log(`  ${pn.phoneNumber} → Agent: ${pn.linkedAgent?.name || 'none'}`);
});

console.log('Queued calls:', affected.queuedCallsCount);
```

***

## Delete credentials

<Warning>
  Deleting credentials also deletes all associated phone numbers and updates affected agents.
</Warning>

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Check impact first
const affected = await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}/affected-agents`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

if (affected.queuedCallsCount > 0) {
  console.log('Warning: calls in queue will fail');
}

// Delete with force flag if phone numbers exist
await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}?force=true`,
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);
```

***

## Troubleshooting

### Authentication failures

| Error            | Cause                   | Fix                                   |
| ---------------- | ----------------------- | ------------------------------------- |
| 401 Unauthorized | Wrong username/password | Verify credentials in provider portal |
| 403 Forbidden    | IP not whitelisted      | Add Dasha IPs to provider allowlist   |
| Domain mismatch  | Wrong `domain` value    | Check provider's authentication realm |

### Connection issues

| Error                | Cause             | Fix                                           |
| -------------------- | ----------------- | --------------------------------------------- |
| Timeout              | Wrong server/port | Verify `server` address and port              |
| Connection refused   | Wrong transport   | Try `tcp` instead of `udp` (or vice versa)    |
| TLS handshake failed | Certificate issue | Check provider supports TLS; verify port 5061 |

### Rate limiting

| Error                   | Cause                 | Fix                                   |
| ----------------------- | --------------------- | ------------------------------------- |
| 503 Service Unavailable | Exceeded provider CPS | Set `cpsLimit` below provider's limit |
| Calls dropping          | Shared limit exceeded | Use `cpsKey` to combine trunk limits  |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Phone Numbers" icon="phone" href="/docs/deploy/phone-numbers">
    Add and link phone numbers
  </Card>

  <Card title="Caller ID" icon="id-card" href="/docs/deploy/caller-id">
    Configure display names
  </Card>

  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/docs/deploy/inbound-calls">
    Handle incoming calls
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/docs/deploy/outbound-calls">
    Make outbound calls
  </Card>
</CardGroup>