sinch-elastic-sip-trunking

What this skill does

# Sinch Elastic SIP Trunking API

## Overview

The Sinch Elastic SIP Trunking (EST) API lets you programmatically provision SIP trunks and route voice traffic between customer infrastructure and the PSTN. The core workflow is: create a trunk, authorize it (ACL or credentials), attach endpoints, assign phone numbers.

## Agent Instructions

Before generating code, gather from the user (skip any item already specified in the prompt or context):

1. **Direction** — inbound (receive calls from PSTN), outbound (send calls to PSTN), or both?
2. **Auth method for the trunk** (if outbound or both) — ACL-based (static IPs) or Credential-based (digest auth / dynamic IPs)?
3. **Endpoint type** (if inbound or both) — Static endpoint (fixed IP/port) or Registered endpoint (SIP UA registers dynamically)?
4. **Approach** — SDK or direct API calls (curl/fetch/requests)?
5. **Language** — for SDK: Node.js. For direct API: any language, or curl. Python, Java, and .NET must use direct HTTP — only Node.js has SDK support.

When the user chooses **SDK**, refer to the [sinch-sdks](../sinch-sdks/SKILL.md) skill for installation and client initialization, then to the API references linked in References.

When the user chooses **direct API calls**, refer to the API references linked in References for request/response schemas.

**Security**: See the Security section below for url fetching policy and credential handling.

## Decision Tree

```
User wants EST →
├─ Outbound only
│  ├─ Static IPs   → Workflow A (Trunk + ACL)
│  └─ Dynamic IPs  → Workflow E (Trunk + Credential List / Digest Auth)
├─ Inbound only
│  ├─ Static IP    → Workflow B (Trunk + Static Endpoint + Phone Number)
│  └─ Dynamic IP   → Workflow D (Trunk + Credential List + Registered Endpoint + Phone Number)
└─ Both           → Workflow C (Trunk + ACL/Creds + Endpoint + Phone Number)
```

## Critical Rules

1. **Dependency order matters.** Creating resources out of order causes failures.
   `Create Trunk` → `Create ACL/Credentials` → `Link to Trunk` → `Assign Phone Numbers` → `Create Endpoint`
2. **The Domain Trap.** Never send SIP INVITEs to `trunk.pstn.sinch.com`. ALWAYS use `{your-hostname}.pstn.sinch.com`.
3. **60-second propagation.** After linking ACLs or Credentials, wait 60 seconds before testing.
4. **Lower priority = higher preference.** Endpoint `priority: 1` is primary; `priority: 100` is failover.
5. **PUT replaces the entire object.** Omitted fields become `null`.

## Getting Started

### Agent Credentials handling

Store credentials in environment variables — never hardcode tokens or keys in commands or source code:

```bash
export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_ACCESS_TOKEN="your-oauth-token"
```

### Authentication

Ensure that authentication headers are properly set when making API calls. The Elastic SIP Trunking API uses Bearer token authentication:

```bash
-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"
```

See [sinch-authentication](../sinch-authentication/SKILL.md) for full setup, most importantly how to obtain `{SINCH_ACCESS_TOKEN}` (OAuth2 client-credentials — do not mint your own JWT).

### SDK Installation

See [sinch-sdks](../sinch-sdks/SKILL.md) for installation and client initialization. Note: EST is only supported in the **Node.js SDK** — for Java, Python, and .NET, use direct HTTP calls.

### First API Call — Create a Trunk

```bash
curl -X POST \
  "https://elastic-trunking.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/trunks" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trunk", "hostName": "my-trunk"}'
```

Response includes `sipTrunkId` and `hostName` — use `{hostName}.pstn.sinch.com` for all SIP routing.

For SDK examples, see the [Getting Started Guide](https://developers.sinch.com/docs/est/getting-started.md).
## Key Concepts

- **Trunk**: Connection between your infrastructure and Sinch. Has a `hostName` used in SIP routing.
- **SIP Endpoint**: Where inbound calls go. **Static** (fixed IP) or **Registered** (dynamic, requires Credential List).
- **ACL**: Authorizes outbound by source IP (CIDR notation, e.g. `203.0.113.10/32`).
- **Credential List**: Username/password pairs. Used for registered endpoint auth (inbound) or digest auth (outbound).
- **Phone Numbers**: E.164 DIDs assigned to a trunk for inbound routing.

## Workflows

### Workflow A: Outbound Only (ACL-based)

- [ ] 1. Create trunk
- [ ] 2. Create ACL with your source IPs
- [ ] 3. Link ACL to trunk
- [ ] 4. **Wait 60 seconds**
- [ ] 5. Verify: `GET /trunks/{trunkId}/accessControlLists` — confirm ACL appears

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create ACL](https://developers.sinch.com/docs/est/api-reference/est/access-control-list/createaccesscontrollist.md) → [Link ACL to trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/addaccesscontrollisttotrunk.md) → [List ACLs for trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/getaccesscontrollistsfortrunk.md)

### Workflow B: Inbound Only (Static Endpoint)

- [ ] 1. Create trunk
- [ ] 2. Create static SIP endpoint on trunk
- [ ] 3. Assign phone number(s) to trunk
- [ ] 4. Verify: `GET /trunks/{trunkId}/endpoints` and `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow C: Bidirectional (Both Inbound + Outbound)

- [ ] 1. Create trunk
- [ ] 2. Create ACL and/or Credential List → Link to trunk
- [ ] 3. Create SIP endpoint on trunk
- [ ] 4. Assign phone numbers to trunk
- [ ] 5. **Wait 60 seconds** before testing
- [ ] 6. Verify: `GET /trunks/{trunkId}/accessControlLists`, `GET /trunks/{trunkId}/endpoints`, `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create ACL](https://developers.sinch.com/docs/est/api-reference/est/access-control-list/createaccesscontrollist.md) → [Link ACL to trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/addaccesscontrollisttotrunk.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow D: Inbound with Registered Endpoint (Credential-based)

- [ ] 1. Create trunk
- [ ] 2. Create credential list with username/password
- [ ] 3. Create registered endpoint on trunk (references a username from the credential list)
- [ ] 4. Assign phone number(s) to trunk
- [ ] 5. Configure SIP UA to REGISTER to `{hostname}.pstn.sinch.com`
- [ ] 6. Verify: `GET /trunks/{trunkId}/endpoints` and `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Credential Lists](https://developers.sinch.com/docs/est/api-reference/est/credential-lists/getcredentiallistbyid.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow E: Outbound Only (Digest Auth / Credential-based)

- [ ] 1. Create trunk
- [ ] 2. Create credential list with username/password
- [ ] 3. Link credential list to trunk
- [ ] 4. **Wait 60 seconds**
- [ ] 5. Verify: `GET /trunks/{trunkId}/credentialLists` — confirm credential list appears

**API docs**: [Create trunk](https://developers.sin