API Keys & Integration Setup

Avatar
Wilson Serge Shalo Mbensie
Follow

API keys allow you to integrate Shaloz with your e-commerce platform, custom applications, or third-party systems. This guide explains how to generate, manage, and use API keys securely.

__________________________________________________

What Are API Keys?

Definition:

API keys are secure credentials that authenticate your application when making requests to the Shaloz API.

Two Types:

1. Public Key (pk\_)

  • Starts with pk_sandbox_ or pk_live_
  • Safe to use in client-side code
  • Used for rate lookups
  • Can be exposed in JavaScript, mobile apps
  • Limited capabilities (read-only operations)

2. Secret Key (sk\_)

  • Starts with sk_sandbox_ or sk_live_
  • Must be kept secret
  • Used for creating fulfillments
  • Server-side only
  • Full API capabilities
  • Never expose in client code

__________________________________________________

Business ID (Business Token)

What It Is:

  • Your unique business identifier
  • Format: alphanumeric string
  • Used alongside API keys in some requests

Where to Find:

  1. Navigate to Settings page
  2. Scroll to API Credentials section
  3. See "Business ID" (businessToken)
  4. Copy button next to ID

When You Need It:

  • Some API endpoints require it
  • WooCommerce plugin configuration
  • Custom integrations

Security:

  • Treat as sensitive (like API keys)
  • Don't share publicly
  • Used for authentication

__________________________________________________

Sandbox vs. Production Environments

Sandbox Environment:

Purpose:

  • Testing integrations
  • Development work
  • Training staff
  • Experimenting with features

Characteristics:

  • No real charges - Test payments don't process
  • No real deliveries - Drivers don't get notified
  • Separate data - Orders don't mix with production
  • Safe testing - Can't accidentally create real deliveries

Use Cases:

  • Developing WooCommerce integration
  • Testing API calls
  • Training new team members
  • Debugging issues

Production Environment:

Purpose:

  • Live operations
  • Real customer deliveries
  • Actual charges and payments

Characteristics:

  • Real charges - Payments process for real
  • Real deliveries - Drivers receive and complete orders
  • Live data - Actual business operations
  • Careful use - Mistakes affect real customers

Use Cases:

  • Live e-commerce store
  • Production applications
  • Actual customer orders

Switching:

  • Use environment toggle in header
  • Separate API keys for each environment
  • Never mix sandbox/production keys

__________________________________________________

Generating API Keys

Step-by-Step:

1. Navigate to Settings Page

2. Scroll to "API Keys" Section

3. Click "Create API Key" Button

4. Select Environment:

  • Sandbox - For testing
  • Production - For live use

5. Optional: Name Your Key

  • Descriptive label
  • Examples:
  • "WooCommerce Integration"
  • "Custom Mobile App"
  • "Partner System"
  • Helps identify key's purpose
  • Not required but recommended

6. Click "Generate Key"

7. Key Generated:

  • Public Key displayed
  • Secret Key displayed
  • Copy immediately - Secret key shown only once
  • Store securely - Can't retrieve secret key later

8. Save Both Keys:

  • Copy public key
  • Copy secret key
  • Store in password manager or environment variables
  • Never commit to Git or share publicly

9. Key Appears in List:

  • Masked secret key (sk*live*\*\*\*\*1234)
  • Full public key visible
  • Creation date shown
  • Environment labeled
  • Name/label if provided

__________________________________________________

Viewing API Keys

API Keys Table Shows:

  • Key Name/Label - Descriptive name (if provided)
  • Public Key - Full pk\_ key (visible)
  • Secret Key - Masked sk\_\*\*\*\*1234 (hidden)
  • Environment - Sandbox or Production
  • Created Date - When key was generated
  • Actions:
  • Copy Public Key
  • Delete Key

Security Note:

  • Secret keys are never shown again after creation
  • Only last 4 digits visible
  • If lost, must delete and create new key

__________________________________________________

Using API Keys

For WooCommerce Plugin:

Public Key:

  • Enter in WooCommerce → Settings → Shipping → Shaloz → API Key field
  • Used to fetch real-time shipping rates
  • Safe for WooCommerce (server-side)

Business ID:

  • Also may be required in plugin settings
  • Check plugin documentation

For Custom Integrations:

Public Key (Client-Side):

  • Rate lookup API endpoint: /public/rate-lookup
  • Can be used in JavaScript, mobile apps
  • Request Example:

GET /api/public/rate-lookup
Headers:
  Authorization: Bearer pk_live_abc123xyz
Body:
  {
    "zip": "02101",
    "businessToken": "your-business-id"
  }

Secret Key (Server-Side Only):

  • Create fulfillment endpoint: /fulfilment-packages
  • Must be server-side (Node.js, PHP, Python, etc.)
  • Never in client JavaScript/mobile apps
  • Request Example:

POST /api/fulfilment-packages
Headers:
  Authorization: Bearer sk_live_abc123xyz
  Content-Type: application/json
Body:
  {
    "businessToken": "your-business-id",
    "customer": {...},
    "packages": [...],
    "scheduledDate": "2025-11-15"
  }

__________________________________________________

Best Practices for API Key Security

DO:

Store in Environment Variables

# .env file (never commit to Git)
SHALOZ_SECRET_KEY=sk_live_abc123xyz
SHALOZ_PUBLIC_KEY=pk_live_def456uvw
SHALOZ_BUSINESS_ID=your-business-id

Use Secret Manager

  • AWS Secrets Manager
  • Azure Key Vault
  • Google Cloud Secret Manager
  • HashiCorp Vault

Restrict Access

  • Only developers who need them
  • Use separate keys for different apps
  • Principle of least privilege

Rotate Keys Regularly

  • Every 90 days recommended
  • After staff changes
  • If compromise suspected

Monitor Usage

  • Review API logs
  • Watch for unusual activity
  • Set up alerts

DON'T:

Never Commit to Git

# BAD - Don't do this!
const API_KEY = 'sk_live_abc123xyz'; // Secret exposed!

Never Expose Client-Side

<!-- BAD - Don't do this! -->
<script>
  const secretKey = "sk_live_abc123xyz"; // Exposed!
</script>

Never Share Publicly

  • GitHub issues
  • Stack Overflow
  • Slack/Discord
  • Email to support (use Business ID instead)

Never Hardcode

  • In application code
  • In mobile apps
  • In configuration files committed to source control

__________________________________________________

Rotating API Keys

When to Rotate:

  • Every 90 days (best practice)
  • Key compromised or exposed
  • Employee with access leaves
  • Security audit recommendation
  • Switching from test to production

How to Rotate:

1. Generate New Key:

  • Click "Create API Key"
  • Same environment as old key
  • Copy new public and secret keys

2. Update Integrations:

  • Update environment variables
  • Update WooCommerce plugin settings
  • Update custom applications
  • Test with new keys

3. Verify New Key Works:

  • Test rate lookup (public key)
  • Test fulfillment creation (secret key)
  • Monitor for errors
  • Ensure all integrations updated

4. Delete Old Key:

  • Once new key confirmed working
  • Find old key in list
  • Click "Delete"
  • Confirm deletion

5. Monitor:

  • Watch for any errors
  • Verify all systems using new key
  • Keep new key secure

__________________________________________________

Deleting API Keys

When to Delete:

  • Key compromised
  • No longer using integration
  • Rotating keys
  • Cleaning up old test keys

How to Delete:

1. Click "Delete" Button next to key in list

2. Confirmation Dialog:

  • Warning: "Deleting this key will break any integrations using it"
  • Key details shown

3. Confirm Deletion

4. Key Deleted:

  • Immediately stops working
  • All API requests with that key fail
  • Cannot be recovered

Important:

  • Update integrations BEFORE deleting old key
  • Or have downtime between old key deletion and new key deployment

__________________________________________________

Testing API Keys

Test Connection in WooCommerce:

  1. Enter API key in plugin settings
  2. Click "Test Connection" button
  3. Should show: " API key is valid! Connection successful"
  4. If error, check key is correct and matches environment

Test with API Calls:

Test Public Key (Rate Lookup):

curl -X POST https://api.shaloz.com/public/rate-lookup \
  -H "Authorization: Bearer pk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"zip":"02101","businessToken":"your-business-id"}'

Expected Response:

{
  "available": true,
  "rate": {
    "total": 12.50,
    "distance": 5.2,
    "deliveryFee": 8.00,
    ...
  }
}

Test Secret Key (Fulfillment):

curl -X POST https://api.shaloz.com/fulfilment-packages \
  -H "Authorization: Bearer sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "businessToken":"your-business-id",
    "customer":{"firstName":"John",...},
    "packages":[{...}],
    "scheduledDate":"2025-11-15"
  }'

Expected Response:

{
  "success": true,
  "fulfillmentId": "ful_abc123",
  "trackingUrl": "https://track.shaloz.com/ful_abc123"
}

__________________________________________________

API Key Errors

"Invalid API Key"

Causes:

  • Wrong key entered
  • Extra spaces in key
  • Using sandbox key in production (or vice versa)
  • Key was deleted
  • Copy/paste error

Solutions:

  • Verify key is correct
  • Check environment matches (sandbox/production)
  • Generate new key if lost
  • Copy key carefully (no extra characters)

"Unauthorized"

Causes:

  • Using public key where secret key required
  • Business ID missing or incorrect
  • Key doesn't have permissions

Solutions:

  • Use secret key for fulfillment creation
  • Include businessToken in request
  • Verify business ID correct

"Key Expired" (Future Feature)

Cause: API key expiration policy

Solution:

  • Rotate key
  • Generate new key
  • Update integrations

__________________________________________________

Managing Multiple API Keys

Why Multiple Keys:

  • Different applications
  • Different environments (sandbox, production)
  • Different team members
  • Easier to revoke specific access

Organization:

Name Keys Descriptively:

  • "WooCommerce Production"
  • "Mobile App Sandbox"
  • "Partner Integration"
  • "Development Server"

Track Usage:

  • Note which key is where
  • Document in password manager
  • Spreadsheet or key management tool

Separate by Environment:

  • All sandbox keys in one section
  • All production keys in another
  • Clear labeling

__________________________________________________

Webhooks (Related to Integrations)

See Dedicated Article: Article 2.11: Webhook Configuration

Brief Overview:

  • Webhooks work with API keys
  • Webhook secret separate from API keys
  • Two-way communication (API + Webhooks)

__________________________________________________

API Documentation

Access API Docs:

  1. Navigate to Docs page in portal
  2. Click "REST API" tab
  3. See:
  4. Endpoint reference
  5. Request/response examples
  6. Authentication instructions
  7. Code samples

Endpoints Documented:

  • /public/rate-lookup (Public key)
  • /fulfilment-packages (Secret key)
  • Request format
  • Response format
  • Error codes

__________________________________________________

Need Help?

Can't Generate API Key?

  • Refresh page
  • Try different browser
  • Contact support: help.shaloz.com

API Key Not Working?

  • Verify key matches environment
  • Check for extra spaces
  • Test with different endpoint
  • Regenerate key

Lost Secret Key?

  • Cannot retrieve lost secret keys
  • Delete old key
  • Generate new key
  • Update integrations

Integration Questions?

  • Check Docs page in portal
  • WooCommerce: See Article 3.X
  • Contact support for custom integrations
Was this article helpful? 0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.

Can’t find what you’re looking for?

Let us help you!

Submit a request
Support Agent