# Acquire a concurrency lock without proxying

## Goal

Share the same pool concurrency limit and keys as proxy traffic, but perform the upstream
HTTP call from your own process. Typical cases: a connector that cannot rewrite
the base URL, or a worker that must keep the origin client library as-is.

Full request and response shapes live in the
[Concurrency locks API](/docs/api/locks).

## Pattern

1. **Acquire** a slot on `https://api.nthpool.cloud` (not the pool proxy host).
2. Call the upstream yourself while holding the slot.
3. **Renew** about every 10 seconds if the work can exceed one lease term.
4. **Release** when finished. Include throttle fields if the upstream returned
   `429` so adaptive / RPM control can learn.

```bash
export POOL_KEY='nb_live_…'
export LOCK_API='https://api.nthpool.cloud/pools/your-pool/lock'

# Fail fast when the pool is full; add "waitMs" to join the queue.
GRANT=$(curl -sS -X POST "$LOCK_API/acquire" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "Content-Type: application/json")
SLOT_ID=$(printf '%s' "$GRANT" | jq -r .slotId)

# … your upstream call …

curl -sS -X POST "$LOCK_API/$SLOT_ID/release" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":200}'
```

## Auth and credentials

Use the same pool key (and optional HMAC / JWT / Cloudflare Access) as the
proxy. The lock API never emits managed upstream credentials. On a managed pool
you still supply origin auth yourself when you call the upstream.

## See also

- [Concurrency locks API](/docs/api/locks)
- [Concurrency](/docs/pools/concurrency)
- [Access](/docs/pools/access)