> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Gateway

> Use Notte's residential proxies from your own HTTP client, scraper or proxy

> [!TIP]
>
> Read [the Notte skill](https://notte.cc/skill.md) and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

## Overview

The proxy gateway at `proxy.notte.cc` gives you Notte's residential proxies outside a browser session. Use it from curl, an HTTP client, a scraper, or your own proxy, such as a [secret proxy](https://docs.notte.cc/features/sessions/secret-proxies/overview.md) that should exit from the same IP as your session.

You mint a short-lived credential with your API key, then use it as a standard proxy URL. Browser sessions do not need this: their [built-in proxies](https://docs.notte.cc/features/sessions/proxies.md#built-in-proxies) are on by default.

## Mint a credential

Call `POST /proxies/gateway/credentials` with your API key. The SDKs have no method for this endpoint, so call it over HTTP.

```bash cURL theme={null}
curl -X POST https://api.notte.cc/proxies/gateway/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "us", "sticky_session": "checkout-4821"}'
```

All body fields are optional. Any other field is rejected.

| Field | Description |
| - | - |
| `country` | Two-letter country code, such as `us`. Without `country` or `city`, traffic exits in the US. |
| `city` | City id, such as `new.york`. Takes precedence over `country`. An unsupported city returns `400` with examples of supported ones. |
| `sticky_session` | 1 to 64 letters, digits or hyphens. Pins every connection made with the credential to one residential exit. See [Share an exit IP with a session](#share-an-exit-ip-with-a-session). |

```json Response theme={null}
{
  "username": "country-us_sticky-checkout-4821.eyJlIjoi...",
  "password": "kq3V...",
  "expires_at": "2026-11-03T21:00:00Z",
  "proxy_url_tls": "https://country-us_sticky-checkout-4821.eyJlIjoi...:kq3V...@proxy.notte.cc:443",
  "proxy_url_plain": "http://country-us_sticky-checkout-4821.eyJlIjoi...:kq3V...@proxy.notte.cc:3128"
}
```

| Field | Description |
| - | - |
| `proxy_url_tls` | `https://user:pass@proxy.notte.cc:443`. Your client connects to the gateway over TLS. Use it when your client supports HTTPS proxies. |
| `proxy_url_plain` | `http://user:pass@proxy.notte.cc:3128`. For clients that only support HTTP proxies. The credential then travels unencrypted to the gateway, even for `https://` sites, and anyone on the network path can reuse it until it expires. Prefer `proxy_url_tls`. |
| `username`, `password` | The same credential, for clients that take them separately. |
| `expires_at` | When the credential stops working. |

## Send requests through the gateway

Both proxy URLs work for `https://` sites, through a `CONNECT` tunnel, and for plain `http://` URLs. With curl:

```bash cURL theme={null}
# Mint a credential, then send a request through it
PROXY_URL=$(curl -sf -X POST https://api.notte.cc/proxies/gateway/credentials \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "us"}' | jq -er '.proxy_url_tls') || {
  echo "could not mint a gateway credential" >&2
  exit 1
}

curl --proxy "$PROXY_URL" https://api.ipify.org
```

From Python or Node.js:

```python http_client.py theme={null}
import os

import httpx

credential = (
    httpx.post(
        "https://api.notte.cc/proxies/gateway/credentials",
        headers={"Authorization": f"Bearer {os.environ['NOTTE_API_KEY']}"},
        json={"country": "us"},
    )
    .raise_for_status()
    .json()
)

# Every request made with this client exits from a residential IP in the US
with httpx.Client(proxy=credential["proxy_url_tls"]) as http:
    print(http.get("https://api.ipify.org").text)
```

```typescript http_client.ts theme={null}
import https from 'node:https';

const response = await fetch('https://api.notte.cc/proxies/gateway/credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTTE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ country: 'us' }),
});
if (!response.ok) throw new Error(`Minting failed: HTTP ${response.status}`);
const credential = (await response.json()) as { proxy_url_tls: string };

// Requests made with this agent exit from a residential IP in the US (Node.js 24.5+)
const agent = new https.Agent({ proxyEnv: { HTTPS_PROXY: credential.proxy_url_tls } });
https.get('https://api.ipify.org', { agent }, (res) => {
  res.setEncoding('utf8');
  res.on('data', (chunk: string) => process.stdout.write(chunk));
});
```

In Node.js, the `proxyEnv` agent option needs Node.js 24.5 or later and applies to `https.request` and `https.get`, not to `fetch`.

## Share an exit IP with a session

Mint the credential with a `sticky_session`, then start a browser session with the same `sticky_session`, and the same `country` or `city`, on its `notte` proxy. Connections made with the credential and the session's own traffic then exit from the same IP. The [secret proxy guide](https://docs.notte.cc/features/sessions/secret-proxies/overview.md#share-the-exit-ip) shows the full setup.

## Lifetime and renewal

A credential is valid for your plan's maximum session duration, up to 24 hours. You cannot choose a different lifetime. Reuse one credential for every request until it expires, then mint a new one before `expires_at`. An expired credential is rejected with `407`.

## Billing and limits

Traffic through the gateway is billed as built-in proxy bandwidth, at the [built-in proxy rate](https://docs.notte.cc/features/sessions/proxies.md#billing), to the workspace whose API key minted the credential.

| Status | Meaning |
| - | - |
| `407` | The credential is missing, invalid or expired. |
| `402` | The workspace has no remaining balance, or its plan's proxy spend limit is reached. |
| `403` | The target is a private, loopback or link-local address. |
| `429` | Too many credentials minted, or too many connections open at once or opened too quickly. Retry with backoff. |
| `503` | From the mint endpoint: credentials or city targeting are temporarily unavailable. Retry, or omit `city`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.