Brightdata Install Auth

---
name: brightdata-install-auth
description: 'Install and configure Bright Data SDK/CLI authentication.

  Use when setting up a new Bright Data integration, configuring API keys,

  or initializing Bright Data in your project.

  Trigger with phrases like "install brightdata", "setup brightdata",

  "brightdata auth", "configure brightdata API key".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(curl:*), Grep
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- scraping
- data
- brightdata
compatibility: Designed for Claude Code
---
# Bright Data Install & Auth

## Overview

Configure Bright Data proxy credentials, API tokens, and SSL certificates for web scraping. Bright Data uses HTTP proxy protocols and REST APIs — you authenticate via zone credentials from the control panel, not a dedicated npm SDK.

## Prerequisites

- Node.js 18+ or Python 3.10+
- Bright Data account at https://brightdata.com
- A configured zone (Web Unlocker, Scraping Browser, SERP API, or Residential)
- Zone credentials from the Bright Data control panel

## Instructions

### Step 1: Gather Credentials from Control Panel

Log into https://brightdata.com/cp and navigate to your zone's overview tab:

| Credential | Location | Example |
|-----------|----------|---------|
| Customer ID | Settings > Account | `c_abc123` |
| Zone Name | Zone overview tab | `web_unlocker1` |
| Zone Password | Zone overview tab | `z_pass_xyz` |
| API Token | Settings > API tokens | `abc123def456` |

### Step 2: Configure Environment Variables

```bash
# .env (NEVER commit to git)
BRIGHTDATA_CUSTOMER_ID=c_abc123
BRIGHTDATA_ZONE=web_unlocker1
BRIGHTDATA_ZONE_PASSWORD=z_pass_xyz
BRIGHTDATA_API_TOKEN=abc123def456

# .gitignore — add these
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore
```

### Step 3: Download Bright Data SSL Certificate

Required for HTTPS proxy connections through the super proxy:

```bash
curl -sO https://brightdata.com/ssl/brd-ca.crt

# Node.js — set environment variable
export NODE_EXTRA_CA_CERTS=./brd-ca.crt
```

### Step 4: Install HTTP Libraries

```bash
# Node.js
npm install axios dotenv

# Python
pip install requests python-dotenv
```

### Step 5: Verify Connection

```typescript
// verify-brightdata.ts
import axios from 'axios';
import https from 'https';
import 'dotenv/config';

const { BRIGHTDATA_CUSTOMER_ID, BRIGHTDATA_ZONE, BRIGHTDATA_ZONE_PASSWORD } = process.env;

const proxy = {
  host: 'brd.superproxy.io',
  port: 33335,
  auth: {
    username: `brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}`,
    password: BRIGHTDATA_ZONE_PASSWORD!,
  },
};

async function verify() {
  const res = await axios.get('https://lumtest.com/myip.json', {
    proxy,
    httpsAgent: new https.Agent({ rejectUnauthorized: false }),
  });
  console.log('Proxy IP:', res.data.ip);
  console.log('Country:', res.data.country);
  console.log('Connection verified.');
}

verify().catch(console.error);
```

```python
# verify_brightdata.py
import os, requests
from dotenv import load_dotenv

load_dotenv()
proxy_url = (
    f"http://brd-customer-{os.environ['BRIGHTDATA_CUSTOMER_ID']}"
    f"-zone-{os.environ['BRIGHTDATA_ZONE']}"
    f":{os.environ['BRIGHTDATA_ZONE_PASSWORD']}"
    f"@brd.superproxy.io:33335"
)
resp = requests.get(
    'https://lumtest.com/myip.json',
    proxies={'https': proxy_url},
    verify='./brd-ca.crt',
)
print(f"Proxy IP: {resp.json()['ip']}, Country: {resp.json()['country']}")
```

## Output

- `.env` file with zone credentials (git-ignored)
- `brd-ca.crt` SSL certificate for HTTPS proxying
- Successful proxy connection showing rotated IP and country

## Examples

Create a separate least-privilege zone for a defined approved workload, keep its credential in the secret manager, and run one controlled authorization probe without emitting the proxy URL or credentials. Do not reuse personal or broad administrator credentials; record zone owner, target class, and rotation/revocation process before deployment.

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `407 Proxy Authentication Required` | Wrong username format | Use `brd-customer-{ID}-zone-{ZONE}` |
| `SSL: CERTIFICATE_VERIFY_FAILED` | Missing CA cert | Download `brd-ca.crt` |
| `ECONNREFUSED` on port 33335 | Firewall blocking | Allow outbound TCP to `brd.superproxy.io:33335` |
| `403 Forbidden` | Zone not active | Activate zone in control panel |

## Resources

- [Bright Data Control Panel](https://brightdata.com/cp)
- Proxy Setup Docs
- [SSL Certificate](https://docs.brightdata.com/general/account/ssl-certificate)

## Next Steps

After successful auth, proceed to `brightdata-hello-world` for your first scraping request.