Skip to main content

Bulk Credentials Page

Efficiently manage API credentials for multiple sites simultaneously, ideal for initial setup or credential rotation across your site portfolio.

Overview​

The Bulk Credentials page provides a spreadsheet-style interface for entering or updating API credentials for all sites at once. Instead of visiting each site individually in the Site Management page, you can:

  • View all sites in one table
  • Update multiple credentials simultaneously
  • Process changes in efficient batches (10 sites at a time)
  • Only update sites where credentials actually changed

Access: GSM Middleware → Bulk Credentials (menu position 12)

Permission Required: manage_gsm_middleware

Use Cases:

  • Initial setup: Enter credentials for 10+ new sites
  • Credential rotation: Update tokens after security policy change
  • Platform migration: Switch from old API keys to new OAuth tokens
  • Audit: Review which sites have credentials configured

Interface Overview​

Page Header​

Title: "Bulk Credential Entry"

Description: "Enter API credentials for multiple sites at once. Leave fields blank for sites you don't want to update."

Site Tables​

Sites are organized into two separate tables by platform:

  1. BigCommerce Sites — All sites with platform = 'bigcommerce'
  2. WooCommerce Sites — All sites with platform = 'woocommerce'

Each table shows site count in header: "BigCommerce Sites (15)"

BigCommerce Sites Table​

Displayed when: One or more BigCommerce sites exist

Columns​

ColumnDescriptionExample
SiteSite ID and name#5 My Store
Client IDOAuth API client IDabcd1234efgh5678
Access TokenOAuth access tokenxyz789abc456def...

Field Specifications​

Client ID:

  • Format: Alphanumeric string (16-32 characters typical)
  • Placeholder: "Enter Client ID"
  • Where to find: BigCommerce → Settings → API → Store-level API accounts
  • Example: abcd1234efgh5678

Access Token:

  • Format: Long alphanumeric string (64+ characters typical)
  • Placeholder: "Enter Access Token"
  • Where to find: Generated when creating API account in BigCommerce
  • Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Security Note: Tokens are one-time display in BigCommerce. Copy immediately or regenerate if lost.

WooCommerce Sites Table​

Displayed when: One or more WooCommerce sites exist

Columns​

ColumnDescriptionExample
SiteSite ID and name#12 WC Store
Consumer KeyREST API consumer keyck_1234567890abc...
Consumer SecretREST API consumer secretcs_9876543210xyz...

Field Specifications​

Consumer Key:

  • Format: Starts with ck_, followed by 40+ alphanumeric characters
  • Placeholder: "ck_..."
  • Where to find: WooCommerce → Settings → Advanced → REST API → Add key
  • Example: ck_1234567890abcdef1234567890abcdef12345678

Consumer Secret:

  • Format: Starts with cs_, followed by 40+ alphanumeric characters
  • Placeholder: "cs_..."
  • Where to find: Generated alongside consumer key
  • Example: cs_9876543210zyxwvu9876543210zyxwvu98765432

Permissions: Recommend "Read/Write" permissions for full sync capability.

Saving Changes​

Save All Changes Button​

Location: Bottom of page

Button text: "Save All Changes" (or "Saving..." when processing)

Button style: Primary (blue)

Behavior:

  1. Compares current values against original values (from initial page load)
  2. Identifies sites with changed credentials only
  3. Processes updates in batches of 10 to avoid overwhelming server
  4. Shows progress message: "Processing batch 2 of 5 (10 sites)..."
  5. Displays final results with success/error count

Save Process Details​

Change Detection:

  • Only sites with modified credentials are updated
  • If all fields unchanged → Shows info message: "No changes detected"
  • Partial changes supported (e.g., only update Client ID, leave token unchanged)

Batch Processing:

  • Updates sent in parallel batches of 10 sites
  • Prevents timeout on large site portfolios (50+ sites)
  • Shows progress for each batch
  • Continues even if some sites fail

Success Message:

✓ Successfully saved credentials for 25 site(s). 25 sites updated.

Error Message:

Saved 23 sites, but 2 failed:
Site #5 (Store A): Invalid client ID format
Site #12 (Store B): Unauthorized - check token permissions

Common Workflows​

Initial Setup: Adding Credentials for New Sites​

Goal: Configure API access for 15 newly added sites

Steps:

  1. Navigate to Bulk Credentials page
  2. Prepare credential spreadsheet:
    • Export list of site names/IDs
    • Collect API credentials from each platform
    • Organize in Excel/CSV for easy copy-paste
  3. For each BigCommerce site:
    • Copy Client ID from spreadsheet
    • Paste into "Client ID" column
    • Copy Access Token
    • Paste into "Access Token" column
  4. Repeat for WooCommerce sites (Consumer Key/Secret)
  5. Click "Save All Changes"
  6. Wait for success message: "Successfully saved credentials for 15 site(s)"
  7. Verify: Go to Site Management → click any site → verify credentials saved

Time savings: ~2 minutes vs. 20+ minutes updating sites individually

Credential Rotation: Updating Tokens After Security Breach​

Goal: Replace all compromised API tokens organization-wide

Steps:

  1. Generate new credentials for all sites:
    • BigCommerce: Create new API accounts, delete old ones
    • WooCommerce: Regenerate REST API keys
  2. Navigate to Bulk Credentials page
  3. For each site, paste only the new token (leave Client ID/Consumer Key unchanged if not compromised)
  4. Click "Save All Changes"
  5. Monitor results for any failures
  6. Test sync on 1-2 sites to verify new credentials work
  7. Critical: Delete old credentials from platforms immediately after confirming new ones work

Security best practice: Rotate credentials quarterly or after any suspected compromise.

Audit: Reviewing Credential Status​

Goal: Identify which sites have missing or incomplete credentials

Steps:

  1. Navigate to Bulk Credentials page
  2. Review tables:
    • Blank fields = No credentials configured
    • Partially filled rows = Incomplete setup (e.g., Client ID but no token)
    • Filled rows = Credentials configured
  3. Document findings:
    • Site #5: Missing BigCommerce token
    • Site #12: No WooCommerce credentials at all
  4. Fix issues:
    • Enter missing credentials directly in table
    • Or go to Site Management for more detailed configuration
  5. Save and verify

Frequency: Run quarterly audit to catch configuration drift

Bulk Update After Platform Migration​

Goal: Update all sites after switching from API v2 to v3 credentials

Scenario: BigCommerce deprecates old API format, requires OAuth

Steps:

  1. Generate new OAuth credentials for all BigCommerce sites
  2. Export list: Site ID, Name, New Client ID, New Token
  3. Navigate to Bulk Credentials page
  4. Paste all new credentials into BigCommerce table
  5. Click "Save All Changes"
  6. Wait for batch processing to complete
  7. Check for errors (some sites may have API account limits)
  8. Test sync on few sites to verify migration successful
  9. Monitor sync health checks for 24-48 hours

Rollback plan: Keep old credentials for 1 week in case revert needed

Partial Update: Fixing Failed Sites​

Goal: Update credentials for 3 sites that failed during previous batch save

Steps:

  1. Note error message from previous save: 
    Site #5 (Store A): Invalid client ID format
    Site #12 (Store B): Unauthorized - check token permissions
    Site #18 (Store C): Network timeout
  2. Navigate to Bulk Credentials page
  3. Only modify failed sites:
    • Site #5: Correct Client ID format (remove whitespace)
    • Site #12: Generate new token with proper permissions
    • Site #18: Re-enter same credentials (network issue, not credential issue)
  4. Click "Save All Changes"
  5. Should show: "Successfully saved credentials for 3 site(s)"

Efficiency: No need to re-save working sites

Technical Details​

API Endpoints​

Load Sites:

  • GET /wp-json/gsm-middleware/v1/sites
  • Returns all sites with current credential values (masked)

Update Site Credentials:

  • PUT /wp-json/gsm-middleware/v1/sites/{site_id}
  • Body: { bc_client_id, bc_auth_token, wc_consumer_key, wc_consumer_secret }
  • Returns: Updated site object

Batch Processing:

  • Uses Promise.allSettled() for parallel requests
  • Batch size: 10 sites per batch
  • Continues on partial failure (doesn't stop entire process)

Controller: src/API/Sites_REST_Controller.php

Data Storage​

Table: rm_sites

Columns Updated:

ColumnTypePlatformEncrypted
bc_client_idTEXTBigCommerceNo
bc_auth_tokenTEXTBigCommerceYes (plugin handles)
wc_consumer_keyTEXTWooCommerceNo
wc_consumer_secretTEXTWooCommerceYes (plugin handles)

Encryption: Tokens/secrets are encrypted before database storage using WordPress encryption functions.

Related Documentation:

React Component​

Component: assets/js/components/BulkCredentialsPage.jsx

State Management:

  • sites — All sites from API
  • credentials — Current form values
  • originalCredentials — Initial values (for change detection)
  • loading — Initial load state
  • saving — Save in progress state
  • message — Success/error feedback

Key Features:

  • Real-time change detection (compares original vs current)
  • Batch processing with progress updates
  • Error handling per site (reports which failed and why)
  • Auto-masking of existing credentials (shows ••••••• for security)

Security Considerations​

Credential Handling​

✅ DO:

  • Copy credentials directly from source platform (avoid typing manually)
  • Use HTTPS for all API communications
  • Rotate credentials annually or after suspected compromise
  • Limit browser history (use private/incognito mode if concerned)
  • Verify SSL certificate valid before entering credentials

❌ DON'T:

  • Store credentials in plain text outside WordPress (e.g., Excel files without encryption)
  • Share credentials via unencrypted email or chat
  • Use same credentials across multiple sites (each site should have unique keys)
  • Leave credentials visible on screen when away from desk
  • Screenshot credentials for documentation (use placeholder values instead)

Permission Requirements​

Who can access:

  • Users with manage_gsm_middleware capability
  • Default: WordPress Administrators only

Who should NOT have access:

  • Shop Managers (can view orders but shouldn't manage integrations)
  • Editors/Authors (content roles)
  • Customers/Subscribers

Audit logging: All credential updates logged in debug.log with user ID and timestamp:

[2024-12-15 10:30:45] GSM Middleware: User #1 updated credentials for site #5

API Key Security Best Practices​

For BigCommerce:

  1. Use store-level API accounts (not app-level)
  2. Set IP whitelist if server has static IP
  3. Enable webhook signature validation for incoming webhooks
  4. Create separate API accounts per environment (dev, staging, prod)
  5. Delete API account immediately if key compromised

For WooCommerce:

  1. Use "Read/Write" permissions (not "Read/Write/Delete")
  2. Enable webhook signature validation
  3. Use HTTPS for API endpoint (never HTTP)
  4. Regenerate keys if WooCommerce site migrates to new server/domain
  5. Monitor API access logs for suspicious activity

Troubleshooting​

"No changes detected" When I Changed Values​

Cause: Values reverted to original before saving

Solution:

  1. Make changes again in text fields
  2. Verify values are different from original (check for extra spaces)
  3. Click directly in field to ensure it's focused/editable
  4. Try clicking "Save All Changes" immediately after pasting

Save Fails with "Invalid client ID format"​

Cause: Whitespace, invalid characters, or wrong format

Solution:

  1. Check for leading/trailing spaces (common when copy-pasting)
  2. Verify format matches platform requirements:
    • BigCommerce Client ID: Alphanumeric only
    • WooCommerce Consumer Key: Must start with ck_
    • WooCommerce Consumer Secret: Must start with cs_
  3. Copy directly from platform (avoid intermediate copy through text editors)
  4. Remove any line breaks or special characters

Some Sites Save, Others Fail​

Cause: Individual site issues (permissions, format, network)

Solution:

  1. Read error message carefully - identifies which sites failed and why
  2. Fix only the failed sites (leave successful ones unchanged)
  3. Click "Save All Changes" again - only failed sites will re-process
  4. If site repeatedly fails:
    • Go to Site Management page
    • Update that site individually (provides more detailed error messages)
    • Verify credentials work by testing API connection

"Network timeout" During Batch Processing​

Cause: Server timeout on large batches or slow network

Solution:

  1. Reduce number of sites updated at once:
    • Update BigCommerce sites first (click Save)
    • Then update WooCommerce sites separately
  2. Increase PHP timeout in wp-config.php: 
    define( 'WP_TIMEOUT', 120 );
  3. Check server logs for PHP max_execution_time errors
  4. Contact hosting provider if timeout persists (may need server configuration change)

Credentials Save But Sync Still Fails​

Cause: Credentials saved but invalid/incorrect

Solution:

  1. Verify credentials in source platform:
    • BigCommerce: Settings → API → Store-level API accounts → Verify account active
    • WooCommerce: Settings → Advanced → REST API → Check key permissions
  2. Test API connection from Testing Tools page:
    • Run "Test BigCommerce Connection" or "Test WooCommerce Connection"
    • Review error message for specific API issue
  3. Common issues:
    • BigCommerce: Wrong store hash, missing OAuth scopes, IP not whitelisted
    • WooCommerce: Wrong site URL, HTTPS mismatch, firewall blocking API access
  4. Regenerate credentials if validation fails consistently

Best Practices​

  1. Plan before bulk update — Prepare credential spreadsheet first, then paste all at once
  2. Test on one site first — Before bulk updating 50 sites, test new credentials on 1-2 sites
  3. Update during low traffic — Avoid sync disruption by updating credentials during off-peak hours
  4. Keep old credentials for 24 hours — In case rollback needed due to unforeseen issues
  5. Document changes — Note date, reason, and number of sites updated in internal changelog
  6. Verify after save — Check Control Panel health checks to confirm credentials working
  7. Use private/incognito mode — When entering sensitive credentials to avoid browser history
  8. Rotate credentials annually — Proactive security measure even if no breach suspected
  9. Batch by platform — Update all BigCommerce sites together, then all WooCommerce sites
  10. Monitor for 24-48 hours — Watch sync health and error logs after bulk credential update