# HubSpot API Token Setup Guide

**Last Updated:** 2026-02-03

Quick reference guide for setting up HubSpot API token in production. Supports multiple configuration methods.

## Quick Check

Run this command to check current token configuration:

```bash
php v2/scripts/affiliate/check-hubspot-token.php
```

## Configuration Priority Order

The system checks for the API token in this order:

1. **Environment variable** `HUBSPOT_API_TOKEN` (highest priority)
2. **Config file** `v2/config/hubspot-api-key.php` (no server access needed – use FTP or cPanel File Manager to create this file; see Method 1 below)
3. **Fallback token** (used for website forms and partner signup when neither env nor config file is set, so both keep working without server access)

Partner signup (`/v2/api/partner-register.php`) uses the same token source as website forms (e.g. `collect-lead.php`). If you cannot set environment variables, create the config file so your production token is used; otherwise the same fallback as for forms is used for partner registration.

## Never Commit the Token

**Do not** push `hubspot-api-key.php` (with a real token) to GitHub and then add it to `.gitignore`. The file would still exist in git history; anyone with repo access could see the token in past commits. Treat the token as compromised and rotate it in HubSpot if that ever happens.

Keep the token out of the repo entirely. The file `v2/config/hubspot-api-key.php` is already in `.gitignore` — create or edit it only on the server (or in a deploy step that uses a secret).

## Without Server Access (No SSH/Shell)

You can get the token on the server without shell access:

| Option                  | How                                                                                                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **FTP / SFTP**          | Connect with FileZilla or similar → go to `v2/config/` → create `hubspot-api-key.php` with `return ['api_token' => 'pat-eu1-your-token'];`                                                                                        |
| **cPanel File Manager** | cPanel → File Manager → `v2/config/` → New File → `hubspot-api-key.php` → Edit and paste the same content                                                                                                                         |
| **Host env vars**       | If your host has “Environment variables” or “App settings” in the control panel, set `HUBSPOT_API_TOKEN` there; the code already reads it                                                                                         |
| **Deploy secret**       | If you use GitHub Actions or another CI/CD that can write files on deploy, add the token as a secret and have the deploy step create `v2/config/hubspot-api-key.php` from it (token stays in the secret store, never in the repo) |
| **Use fallback**        | If you don’t create the file or set env, partner signup and website forms use the same fallback token and keep working; add the config file when you can so production uses your own token                                        |

## Production Setup Methods

### Method 1: Config File (Recommended - No Server Access Needed)

**Best for:** Users without server access or when environment variables aren't available. Same approach used for website forms and partner signup – token is loaded from code (config file), not from environment variables.

1. **Create the config file** (choose one):

   - **With shell access:** `cp v2/config/hubspot-api-key.php.example v2/config/hubspot-api-key.php`
   - **Without shell access:** Use FTP or cPanel File Manager to upload a new file at `v2/config/hubspot-api-key.php` with the contents below.

2. **Set your token** in the config file:

   ```php
   <?php
   return [
       'api_token' => 'pat-eu1-your-token-here'
   ];
   ```

3. **Set file permissions** (recommended):

   ```bash
   chmod 600 v2/config/hubspot-api-key.php
   ```

4. **Verify configuration:**
   ```bash
   php v2/scripts/affiliate/check-hubspot-token.php
   ```

**Security:** For a **private repo** you can push this file once: add your token to `v2/config/hubspot-api-key.php`, commit and push. Then add `v2/config/hubspot-api-key.php` back to `.gitignore` (uncomment or re-add the line) so future edits are not tracked. For a public repo, never commit the file; use FTP/cPanel or env vars instead.

**Advantages:**

- ✅ Works without server access
- ✅ No web server restart needed
- ✅ Easy to update
- ✅ Works on all hosting providers

### Method 2: Apache/.htaccess

If your server supports `SetEnv` in `.htaccess`:

```apache
# Uncomment and set in .htaccess in your web root
<IfModule mod_env.c>
  SetEnv HUBSPOT_API_TOKEN pat-eu1-your-token-here
</IfModule>
```

**Note:** Some shared hosting providers disable `SetEnv` for security. If this doesn't work, use Method 1 (Config File) instead.

### Method 3: PHP-FPM Pool Configuration

Edit your PHP-FPM pool configuration file (usually `/etc/php-fpm.d/www.conf` or similar):

```ini
env[HUBSPOT_API_TOKEN] = pat-eu1-your-token-here
```

Then restart PHP-FPM:

```bash
sudo systemctl restart php-fpm
# or
sudo service php-fpm restart
```

### Method 4: System Environment

Add to system environment file:

```bash
# Edit /etc/environment (system-wide)
sudo nano /etc/environment

# Add line:
HUBSPOT_API_TOKEN=pat-eu1-your-token-here
```

Or add to server startup script (e.g., `/etc/profile.d/ordio.sh`):

```bash
#!/bin/bash
export HUBSPOT_API_TOKEN=pat-eu1-your-token-here
```

### Method 5: cPanel/Shared Hosting

1. Log into cPanel
2. Navigate to **Environment Variables** (may be under Advanced or Software)
3. Add new variable:
   - **Variable Name:** `HUBSPOT_API_TOKEN`
   - **Value:** `pat-eu1-your-token-here`
4. Save changes

**Note:** If cPanel doesn't support environment variables, use Method 1 (Config File) instead.

### Method 6: Docker/Container

Add to `Dockerfile`:

```dockerfile
ENV HUBSPOT_API_TOKEN=pat-eu1-your-token-here
```

Or set in `docker-compose.yml`:

```yaml
environment:
  - HUBSPOT_API_TOKEN=pat-eu1-your-token-here
```

## Verification

After setting the token (using any method):

1. **Restart web server/PHP-FPM** (if using environment variable methods - Methods 2-6)

2. **Verify token is accessible:**

```bash
php v2/scripts/affiliate/check-hubspot-token.php
```

Expected output (environment variable):

```
✓ HUBSPOT_API_TOKEN environment variable is set
  Token preview: pat-eu1-fbbe01ba-571...
✓ Token format is valid
  Region: eu1
✓ hubspot-config.php loaded successfully
✓ Loaded token matches environment variable
```

Expected output (config file):

```
✗ HUBSPOT_API_TOKEN environment variable is NOT set
✓ Config file found: v2/config/hubspot-api-key.php
  Token preview: pat-eu1-fbbe01ba-571...
✓ Token format is valid
  Region: eu1
✓ hubspot-config.php loaded successfully
✓ Loaded token matches config file
```

3. **Run comprehensive test:**

```bash
php v2/scripts/test-hubspot-config.php
```

This will test all configuration methods and verify priority order.

3. **Test API endpoints:**

```bash
# Test dashboard API (requires authentication)
curl -X GET "https://www.ordio.com/v2/api/affiliate-dashboard-data.php" \
  -H "Cookie: PHPSESSID=your-session-id"
```

Should return JSON response (not 503 error).

## Troubleshooting

### Token Not Found After Setting

**Issue:** Token not accessible after configuration

**Solutions:**

1. **If using environment variable:**

   - Restart web server/PHP-FPM - Environment variables may require restart
   - Check method compatibility - Some methods don't work on all servers
   - Verify syntax - No spaces around `=` in environment files
   - Check permissions - Environment files must be readable by web server user

2. **If using config file:**

   - Verify file exists: `v2/config/hubspot-api-key.php`
   - Check file permissions: Should be readable by web server (600 or 640)
   - Verify file syntax: Must return array with `api_token` key
   - Check for PHP errors in web server error logs

3. **Use config file method** - If environment variables don't work, use Method 1 (Config File) which works on all servers

### Still Getting 503 Errors

**Issue:** APIs still return 503 "Service temporarily unavailable. Configuration incomplete."

**Check:**

1. Run `php v2/scripts/affiliate/check-hubspot-token.php` - Does it show token is set?
2. Run `php v2/scripts/test-hubspot-config.php` - Comprehensive configuration test
3. Check web server error logs for configuration errors
4. Verify token format: Must start with `pat-eu1-` or `pat-na1-`
5. Verify production detection: Check if hostname matches `ordio.com`

**Quick Fix:**

If you don't have server access, use the config file method:

```bash
cp v2/config/hubspot-api-key.php.example v2/config/hubspot-api-key.php
# Edit file and set your token
php v2/scripts/affiliate/check-hubspot-token.php
```

**Note:** Read-only affiliate dashboard APIs (`affiliate-dashboard-data.php`, `affiliate-levels.php`) will work with fallback token temporarily, but you should set the token for production.

### Token Format Invalid

**Issue:** Token doesn't match expected format

**Expected format:** `pat-{region}-{hash}`

**Examples:**

- ✅ `pat-eu1-fbbe01ba-571e-425f-9d6a-38a7acb9ee4a`
- ✅ `pat-na1-12345678-90ab-cdef-1234-567890abcdef`
- ❌ `pat-eu1-invalid` (too short)
- ❌ `your-token-here` (wrong format)

## Security Best Practices

- ✅ **Never commit tokens** to version control
- ✅ **Config file is in `.gitignore`** - Automatically excluded from Git
- ✅ **Set restrictive permissions** on config file: `chmod 600 v2/config/hubspot-api-key.php`
- ✅ **Prefer environment variables** when server access is available
- ✅ **Use config file** when environment variables aren't available (still secure)
- ✅ **Rotate tokens** if exposed or compromised
- ✅ **Restrict token scopes** to minimum required
- ✅ **Monitor token usage** in HubSpot Settings → Integrations → Private Apps

## Related Documentation

- **[HubSpot Setup Guide](HUBSPOT_SETUP.md)** - Complete HubSpot integration setup
- **[Deployment Checklist](DEPLOYMENT_CHECKLIST.md)** - Full deployment checklist
- **[API Reference](API_REFERENCE.md)** - API endpoints reference

## Support

If you encounter issues:

1. Run diagnostic script: `php v2/scripts/affiliate/check-hubspot-token.php`
2. Check web server error logs
3. Verify token in HubSpot Settings → Integrations → Private Apps
4. Contact: hady@ordio.com