Intended Audience

This page describes who the intended audience for tlsproxy is and what background knowledge you are expected to bring before working with its API. Understanding the intended audience helps you assess whether tlsproxy fits your use case and how to interpret the rest of this documentation. If you find concepts unfamiliar, the related concepts section at the bottom points to foundational material.

Who this documentation is written for

tlsproxy is designed for developers and system operators who need to terminate TLS connections at a proxy layer and forward the decrypted traffic to backend services that speak plain HTTP or another unencrypted protocol. This documentation assumes you are consuming tlsproxy as an API — meaning you interact with it primarily through HTTP requests to configure, inspect, and control the proxy at runtime.

Expected technical background

You will get the most out of this documentation if you already have a working understanding of the following:

• TLS/SSL fundamentals — You understand what TLS termination means, why it is useful to offload it from application servers, and the difference between a certificate authority, a server certificate, and a private key.
• HTTP and REST conventions — Because tlsproxy exposes an HTTP API, you should be comfortable reading request/response examples, understanding HTTP verbs (GET, POST, PUT, DELETE), and interpreting status codes such as 200 OK, 400 Bad Request, and 502 Bad Gateway.
• Networking basics — Familiarity with concepts like ports, hostnames, upstream vs. downstream, and TCP connections will help you configure routes and debug connectivity issues.
• Twisted or event-driven Python (helpful but not required) — tlsproxy is built on the Twisted framework. You do not need to write Twisted code to use tlsproxy, but knowing that it uses an asynchronous, event-driven model helps you reason about connection behaviour and error messages you may see in logs.

What you do not need to know

You do not need to modify or understand tlsproxy's internal source code to follow this documentation. The workflows covered here — installing the proxy, configuring it via the API, starting and stopping it, and verifying that connections flow correctly — are all achievable through the documented HTTP interface without reading Python.

Skill level

This documentation targets an intermediate level. Step-by-step instructions are provided for core workflows, but explanations assume you can interpret a curl command, read a JSON payload, and consult your operating system's process management tools without detailed hand-holding on those subtopics.

The following example illustrates the kind of interaction this documentation teaches. It is a representative taste of the API style; full endpoint references appear in the API reference section.

Checking which audiences or roles your credentials grant access to (illustrative health-check call)

curl -X GET https://localhost:8443/api/v1/status \
  -H "Accept: application/json"

Expected response when the proxy is running and your request is properly formed:

{
  "status": "ok",
  "version": "1.0",
  "tls_termination": "active",
  "backend": "reachable"
}

If you receive a 401 Unauthorized or 403 Forbidden response, your credentials or API token are either missing or do not have permission to query this endpoint. Refer to the Authentication page for how to obtain and pass a valid token.

• TLS Termination Overview — Explains what TLS termination is, why proxies perform it, and how tlsproxy fits into a typical service architecture.
• Authentication — Describes how to obtain credentials and pass them with every API request.
• API Reference — The full catalogue of HTTP endpoints, request parameters, and response schemas.
• Installation and Setup — How to install tlsproxy and prepare your environment before making API calls.
• Error Handling — A reference for the HTTP status codes and error response bodies that tlsproxy returns, and what they mean for your integration.