nthbouncer
Log inGet started

Quickstart

Prerequisites

  • An nthbouncer account (sign up at nthbouncer.com)
  • An upstream API URL you are allowed to call
  • A tool that can send HTTP requests (curl is enough)

Create a pool

  1. Open the dashboard and select Pools → Create pool.
  2. Choose a subdomain (this becomes ‹subdomain›.nthpool.cloud).
  3. Add at least one origin (the upstream base URL).
  4. Pick Pass-through if your client already authenticates to the upstream, or Managed if nthbouncer should attach credentials for you.
  5. Save. The pool goes live within a few seconds.

Create a pool key

  1. Open the pool → Access.
  2. Select Create key, name it, and copy the secret once.
  3. Store it as an environment variable. It is not shown again.

Send a request

Replace the placeholders and call your pool hostname. The path after the host is forwarded to the selected origin.

export POOL_KEY='nb_live_…'
export POOL_HOST='https://your-pool.nthpool.cloud'

curl -sS "$POOL_HOST/your/api/path" \
  -H "X-Nthpool-Key: $POOL_KEY"

On a managed pool you may also send Authorization: Bearer $POOL_KEY. On a pass-through pool, keep the pool key in X-Nthpool-Key and put the upstream credential in Authorization (or whatever the upstream expects).

If the pool has multiple origins, pick one explicitly:

curl -sS "$POOL_HOST/your/api/path" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "X-Nthpool-Origin: https://api.example.com"

Confirm admission

A successful response includes headers such as x-nthpool-remaining-slots and x-nthpool-effective-limit. Open the pool's Logs page to see the request in access logs, or Metrics for admit/queue/reject proof (not the same as Billing allowance).

Next steps