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

# API quickstart

> Create an API key, verify it, list your packages, and generate a proxy connection string — with curl, Python, and Node.js examples.

This guide takes you from zero to a working integration: you'll create an API key, verify it works, list your proxy packages, and generate a connection string you can plug straight into your proxy client.

## 1. Create an API key

1. Log in to the [dashboard](https://platform.soax.com).
2. Go to [**Settings → API keys**](https://platform.soax.com/settings/api-keys).
3. Click **Generate new API key**, give it a name, and pick its scopes. For this walkthrough you need at least `proxy:packages:read`.
4. Optionally restrict the key to specific packages — a restricted key can only see and act on those packages.
5. Copy the secret. It starts with `s_live_` and is **shown only once** — store it somewhere secure right away.

<Warning>
  Treat the secret like a password. Don't commit it to source control or embed it in client-side code. If a key leaks, [revoke it](/api/keys/revoke) and create a new one.
</Warning>

## 2. Verify the key

Call [`GET /v1/api-keys/me`](/api/keys/me) — it needs no scope and echoes back what the key can do:

```bash theme={null}
curl https://api.platform.soax.com/v1/api-keys/me \
  -H "Authorization: Bearer s_live_YOUR_API_KEY"
```

```json theme={null}
{
  "id": "3f8a2c1e-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
  "scopes": ["proxy:packages:read"],
  "package_ids": null,
  "org_id": "0b9c8d7e-6f5a-4b3c-2d1e-0f9a8b7c6d5e",
  "rate_limit": { "configured_limit": "5/second", "remaining_quota": 4 }
}
```

If you get `401 {"detail": "Invalid API key"}` instead, check that the header is exactly `Authorization: Bearer <secret>` and that the key hasn't been revoked.

## 3. List your packages

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.platform.soax.com/v1/proxy/packages \
    -H "Authorization: Bearer s_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "s_live_YOUR_API_KEY"
  BASE_URL = "https://api.platform.soax.com/v1"

  resp = requests.get(
      f"{BASE_URL}/proxy/packages",
      headers={"Authorization": f"Bearer {API_KEY}"},
  )
  resp.raise_for_status()

  for pkg in resp.json()["data"]:
      print(pkg["id"], pkg["name"], pkg["status"])
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "s_live_YOUR_API_KEY";
  const BASE_URL = "https://api.platform.soax.com/v1";

  const resp = await fetch(`${BASE_URL}/proxy/packages`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

  const { data } = await resp.json();
  for (const pkg of data) console.log(pkg.id, pkg.name, pkg.status);
  ```
</CodeGroup>

```json theme={null}
{
  "data": [
    {
      "id": "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "Residential - EU scraping",
      "status": "active",
      "status_reason": null,
      "created_at": "2026-03-15T12:00:00Z",
      "types": ["wifi"],
      "tiers": [1, 2, 3],
      "allowed_countries": null,
      "traffic_limit": 500000000000,
      "traffic_spent": 120000000000,
      "traffic_left": 380000000000
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Grab the `id` of the package you want to use — you'll need it in the next step.

## 4. Generate a connection string

The [connection-string endpoint](/api/packages/connection-string) builds proxy credentials for you, with targeting rules already encoded — no need to construct the username format by hand:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.platform.soax.com/v1/proxy/packages/b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e/connection-string?protocol=http&country=us" \
    -H "Authorization: Bearer s_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  resp = requests.get(
      f"{BASE_URL}/proxy/packages/{package_id}/connection-string",
      headers={"Authorization": f"Bearer {API_KEY}"},
      params={"protocol": "http", "country": "us"},
  )
  resp.raise_for_status()
  conn = resp.json()[0]
  print(conn["uri"])
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ protocol: "http", country: "us" });
  const csResp = await fetch(
    `${BASE_URL}/proxy/packages/${packageId}/connection-string?${params}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  if (!csResp.ok) throw new Error(`HTTP ${csResp.status}`);
  const [conn] = await csResp.json();
  console.log(conn.uri);
  ```
</CodeGroup>

```json theme={null}
[
  {
    "uri": "http://country-us:aB3dE5fG7h@proxy.soax.com:1337",
    "username": "country-us",
    "password": "aB3dE5fG7h",
    "host": "proxy.soax.com",
    "port": 1337
  }
]
```

## 5. Use it

The returned `uri` is a standard proxy URL — pass it to any HTTP client:

<CodeGroup>
  ```bash curl theme={null}
  curl -x "http://country-us:aB3dE5fG7h@proxy.soax.com:1337" \
    https://checker.soax.com/api/ipinfo
  ```

  ```python Python theme={null}
  proxies = {"http": conn["uri"], "https": conn["uri"]}
  ip = requests.get("https://checker.soax.com/api/ipinfo", proxies=proxies)
  print(ip.json())
  ```
</CodeGroup>

You're routed through a US IP. From here you can add sessions, rotation, and finer targeting (region, city, ISP, ASN, ZIP) via the same endpoint's query parameters.

## Next steps

<CardGroup cols={2}>
  <Card title="Get connection strings" icon="plug" href="/api/packages/connection-string">
    All targeting, session, and rotation parameters.
  </Card>

  <Card title="Authentication & scopes" icon="key" href="/api/authentication">
    What each scope unlocks, and how to manage keys programmatically.
  </Card>

  <Card title="Usage analytics" icon="chart-line" href="/api/analytics/summary">
    Pull traffic and credit usage into your own reporting.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/api/rate-limits">
    Stay under the limits and handle 429s gracefully.
  </Card>
</CardGroup>