BinaryLane scoped API proxy

An experimental, self-hosted APISIX gateway that keeps a BinaryLane master API token on one server and gives users short-lived JWT credentials with mapped roles.

Important

This is Blake Kirkham's personal community project. It is not a BinaryLane product, is not developed or supported by BinaryLane, and is not a substitute for native scoped API tokens. You operate and secure it yourself. Review the code and test the policy against your requirements before using it.

Why it exists

BinaryLane API tokens currently grant account-wide API access. This project is one possible customer-managed workaround when sharing that master token is not acceptable.

The gateway:

• validates per-user HMAC-SHA256 JWTs;
• injects the master BinaryLane token only on the upstream request;
• maps requests to explicit actions and roles;
• fails closed for unknown or newly introduced API operations; and
• keeps APISIX's proxy and admin interfaces off the public network.

The built-in roles are readonly, support, senior-support, billing, and admin. The role names are examples, not a security guarantee. Inspect manifest/roles.json before deployment.

Architecture

User or integration
  |  Authorization: Bearer <short-lived JWT>
  v
Caddy (HTTPS) -> APISIX (JWT + policy) -> BinaryLane API
                                            ^
                                            | master token, held on the VPS

The stack uses APISIX 3.17, etcd 3.5.9, Caddy 2, and Docker Compose on a single Ubuntu 24.04 VPS.

Quick start with cloud-init

Prerequisites:

• a BinaryLane API token;
• an Ubuntu 24.04 VPS (std-1vcpu or larger is recommended);
• SSH access; and
• either a DNS name for public HTTPS, or a private VPC/VPN/tunnel path.

1. Paste this small cloud-init include into the VPS cloud-init/user-data field:

   #include
   https://raw.githubusercontent.com/01ax/binarylane-scoped-api-proxy/345182cc82741b702e9eaa792c34052bf9454b72/generated/bl-scoped-gateway-cloud-init.yaml

   It downloads the reviewed payload at first boot. The URL is pinned to a specific commit so repeated deployments use the same configuration. The VPS needs outbound HTTPS access to raw.githubusercontent.com during first boot. See generated/bl-scoped-gateway-cloud-init.include.yaml for a copyable file, or review the complete generated/bl-scoped-gateway-cloud-init.yaml before deploying.

2. Wait for cloud-init and Docker image pulls to finish.

3. SSH into the VPS and run:

   sudo /opt/bl-proxy/scripts/activate.sh

4. Enter the BinaryLane API token only when activation asks for it. The token is not embedded in the cloud-init payload.

5. Choose public HTTPS or private HTTP and create the initial users.

6. Read /opt/bl-proxy/DEPLOYMENT-NOTES.txt and check the deployment:

   sudo /opt/bl-proxy/scripts/status.sh

Do not expose private HTTP directly to the internet. For public access, use the DNS/HTTPS mode and restrict ingress further wherever practical.

The include is used only at first boot; it does not update an existing VPS when the repository changes. To deliberately deploy a newer revision, review that revision and use its pinned include URL.

Users and JWTs

Add or rotate a user:

sudo /opt/bl-proxy/scripts/add-user.sh alice readonly

The user's role and generated signing secret are written under /opt/bl-proxy/secrets/. Generate a JWT and call the proxy with:

TOKEN=$(sudo /opt/bl-proxy/scripts/make-jwt.sh alice '<user-secret>')
curl -H "Authorization: Bearer $TOKEN" https://proxy.example.com/v2/servers

Never place the master API token, a user secret, or a JWT in a URL, repository, cloud-init payload, shell history, or support ticket.

Build and validation

The generated cloud-init file is built from the source files in this repository:

python3 scripts/build-cloud-init.py
./scripts/validate-cloud-init.sh

The current policy check accounts for 116 API operations: 115 are explicitly mapped and the generic server-action operation is deliberately denied unless its request-body action type is recognised. This result reflects the bundled OpenAPI document and can drift as the upstream API changes.

Security and maintenance

• Treat this gateway as security-sensitive infrastructure.
• Keep the host, container images, dependencies, and role manifest updated.
• Restrict SSH, ports 80/443, and all private network paths.
• Never expose APISIX admin port 9180, proxy port 9080, or etcd port 2379.
• Rotate the master API token and user secrets after suspected disclosure.
• Re-run policy coverage checks whenever the BinaryLane API changes.
• Back up configuration, but never commit .env, generated secrets, logs, or deployment notes.

See SECURITY.md before deployment. Issues and pull requests are welcome, but there is no support or uptime commitment.

Licence

MIT. See LICENSE.