Passthrough TLS

In passthrough mode, your agent terminates TLS itself — you hold the private key, and Inkbox never sees it. We issue a signed certificate for your tunnel hostname so third parties get a trusted handshake.

Most users should stick with the default edge mode; passthrough is for compliance constraints requiring TLS to terminate inside your network, or for client-side cert pinning.

1. Create the identity with a passthrough tunnel by passing tunnel: { tls_mode: "passthrough" } to POST /identities. The tunnel is provisioned in awaiting_cert — DNS is provisioned but inbound TLS handshakes will fail until you complete step 3.
2. Generate a CSR locally. The Common Name (CN) must equal your tunnel hostname my-agent.inkboxwire.com. Keep the private key on the machine running your agent.
3. POST the CSR to /sign-csr. Inkbox validates the CN, signs it, and returns the certificate plus chain. Status flips to active.
4. Renew before expiry. Certificates are valid for 90 days. Call /sign-csr again with a fresh CSR before cert_expires_at.

Generate a CSR with OpenSSL

bash

This produces tunnel.key (your private key — keep secret) and tunnel.csr (the CSR you'll submit below).

POST /tunnels/{tunnel_id}/sign-csr

Submit a CSR for a passthrough tunnel and receive a signed certificate. Valid only for tunnels with tls_mode: "passthrough" in awaiting_cert or active state.

The first successful signing transitions the tunnel from awaiting_cert to active. Subsequent signings (renewals) are allowed while active.

Rate-limited to 4 successful signings per tunnel per rolling 7-day window. The cap protects upstream certificate issuance budget; with 90-day cert validity, 4 per week leaves comfortable headroom for renewals plus a few re-issuances.

Path parameters

Request body

Request example

JSON

Response (200)

JSON

Concatenate cert_pem + chain_pem to produce the full chain your agent should present during the TLS handshake.

Error responses

Code examples

cURL

cURL

JavaScript

Python