Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Connect Secret
description: Rotate the connect secret used by your agent to authenticate to a tunnel

---


# Connect Secret

Each tunnel has a `connect_secret` that your agent presents when opening its persistent connection. The secret is shown **once** at tunnel creation. If you lose it or suspect it's been compromised, rotate it.

---

## Rotate connect secret `POST`


Generate a new `connect_secret` for this tunnel. The new secret is shown **once** in the response — store it securely.

> **Existing live connections are not actively kicked off.** They keep serving traffic until the agent reconnects (idle drop, deploy, restart), at which point the old secret is rejected and the agent must present the new one. To cut over hard, restart your agent immediately after rotating.

Rate-limited to 5 successful rotations per tunnel per day.

### Path parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `tunnel_id` | UUID | Tunnel ID |

### Response (200)

```json
{
    "connect_secret": "tnl_a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9"
}
```

### Error responses

| Status | Description |
| :--- | :--- |
| 404 | Tunnel not found in your organization |
| 429 | Daily rotation rate limit exceeded |

### Code examples

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/tunnels/TUNNEL_ID/rotate-secret" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch(
    `https://inkbox.ai/api/v1/tunnels/${tunnelId}/rotate-secret`,
    {
        method: "POST",
        headers: { "X-API-Key": "YOUR_API_KEY" },
    }
);
const { connect_secret } = await response.json();
```

**Python**

```python
import requests

response = requests.post(
    f"https://inkbox.ai/api/v1/tunnels/{tunnel_id}/rotate-secret",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_secret = response.json()["connect_secret"]
```