# Salesforce Connected App Setup Guide


**Last Updated:** 2025-11-20

**Purpose:** Create a Connected App for OAuth2 API authentication to enable programmatic access to Salesforce (e.g., deleting test contacts).

## Step-by-Step Instructions

### Step 1: Navigate to Connected Apps

1. In Salesforce, go to **Setup** (gear icon in top right)
2. In the Quick Find box, type: **"App Manager"** or **"Connected Apps"**
3. Click on **"App Manager"** or navigate to:
   - **Setup** → **Platform Tools** → **Apps** → **App Manager**
   - Or directly: **Setup** → **Platform Tools** → **Apps** → **Connected Apps** → **Manage Connected Apps**

### Step 2: Create New Connected App

1. Click the **"New Connected App"** button (or **"New"** → **"Connected App"**)
2. If you don't see this option, look for **"New External Client App"** button

### Step 3: Fill in Basic Information

**Connected App Name:**
- Enter: `Ordio API Access` (or any descriptive name)

**API Name:**
- Will auto-populate based on Connected App Name
- Example: `Ordio_API_Access`

**Contact Email:**
- Enter: `constantin@ordio.com` (or your email)

**Description:**
- Enter: `API access for programmatic contact/lead management`

### Step 4: Enable OAuth Settings

1. Check the box: **"Enable OAuth Settings"**

2. **Callback URL:**
   - Enter: `https://login.salesforce.com/services/oauth2/success`
   - Or: `https://localhost/services/oauth2/success` (for local development)

3. **Selected OAuth Scopes:**
   - Move these scopes from "Available OAuth Scopes" to "Selected OAuth Scopes":
     - ✅ **"Access and manage your data (api)"**
     - ✅ **"Perform requests on your behalf at any time (refresh_token, offline_access)"**
     - ✅ **"Access your basic information (id, profile, email, address, phone)"**

4. **OAuth Policies:**
   - **"Permitted Users":** Select **"All users may self-authorize"** or **"Admin approved users are pre-authorized"**
   - **"IP Relaxation":** Select **"Relax IP restrictions"** (or configure specific IPs if needed)
   - **"Refresh Token Policy":** Select **"Refresh token is valid until revoked"**

5. **⚠️ CRITICAL:** Check the box: **"Enable OAuth Username-Password Flows"**
   - This is required for the Username/Password OAuth2 flow we're using

### Step 5: Save and Get Credentials

1. Click **"Save"** (may take a few seconds)
2. Salesforce will display a warning about waiting 2-10 minutes for changes to propagate - you can proceed

3. **After saving, you'll see:**
   - **Consumer Key** (this is your `CLIENT_ID`)
   - **Consumer Secret** (this is your `CLIENT_SECRET`) - Click "Click to reveal" to see it

4. **⚠️ IMPORTANT:** Copy both values immediately - you won't be able to see the Consumer Secret again!

### Step 6: Add Credentials to Config

Add the Consumer Key and Consumer Secret to `v2/config/salesforce.php`:

```php
define('SALESFORCE_CLIENT_ID', 'your-consumer-key-here');
define('SALESFORCE_CLIENT_SECRET', 'your-consumer-secret-here');
```

### Step 7: Test Authentication

Run the cleanup script to test:

```bash
php scripts/salesforce/cleanup-test-contacts.php
```

## Troubleshooting

### "invalid_client_id" Error
- Wait 2-10 minutes after creating the Connected App for changes to propagate
- Verify Consumer Key is correct (no extra spaces)
- Ensure "Enable OAuth Username-Password Flows" is checked

### "invalid_grant" Error
- Verify username and password are correct
- If using security token, ensure it's appended to password correctly
- Check that the user has API access enabled

### "insufficient access rights" Error
- Ensure the user has permissions to query/delete Lead and Contact objects
- Check object-level security settings

## Security Notes

- **Consumer Secret** is sensitive - treat it like a password
- Store credentials securely (environment variables or config file with restricted access)
- Consider IP restrictions if possible
- Use "Admin approved users" if you don't need self-authorization

## Alternative: Using Security Token (SOAP API)

If you prefer not to create a Connected App, you can:
1. Get your Security Token from Salesforce
2. Use SOAP API instead of REST API
3. Update the script to use SOAP authentication

However, REST API with Connected App is the recommended modern approach.