API authentication and scoped keys

All external API requests to SalesPro Hub must be authenticated using an API key. This guide covers how to create, manage, and use API keys.

Creating an API Key

1. Log in as an admin user.
2. Navigate to Settings > API Keys.
3. Click Create API Key.
4. Fill in:
   • Name — A descriptive label (e.g., "Sage Production", "Warehouse Sync").
   • Permissions — Select one or more scopes (see below).
   • Expiration — Optionally set an expiry date. Leave empty for no expiration.
5. Click Create.
6. Copy the key immediately. It starts with sk_ and is only shown once.

Permissions

Each API key has one or more permission scopes that control what it can access:

You can create separate keys with different permissions. For example:

• A read-only key for your BI/reporting tool (orders:read, inventory:read)
• A full-access key for your ERP (orders:read, orders:write, inventory:read, inventory:write)
• A CRM sync key that cannot touch orders or stock (customers:read, customers:write)
• A Zapier key limited to subscription management (zapier:read, zapier:write)

Using Your API Key

Include your key in every request using one of these methods:

Option 1: X-API-Key Header (Recommended)

curl -X GET "https://portal.salesrepsoftware.co.za/api/v1/orders" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Accept: application/json"

Option 2: Bearer Token

curl -X GET "https://portal.salesrepsoftware.co.za/api/v1/orders" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Accept: application/json"

Both methods are equivalent. Use whichever fits your system better.

Managing API Keys

Viewing Keys

The API Keys page shows all keys for your organisation:

• Name
• Permissions (as badges)
• Last used timestamp
• Expiration date
• Status (Active, Disabled, Expired)

Disabling a Key

Click the toggle button on any key to disable it. Disabled keys are immediately rejected. You can re-enable them at any time.

Deleting a Key

Click the delete button and confirm. Deletion is permanent. Any system using that key will lose access immediately.

Key Expiration

Keys with an expiration date automatically stop working after that date. The key remains visible in your list with an "Expired" badge but cannot be used.

Security Best Practices

1. Use separate keys for each integration — If one system is compromised, revoke just that key.
2. Use minimum required permissions — A reporting tool only needs read access.
3. Set expiration dates — Rotate keys periodically, especially for third-party integrations.
4. Never expose keys in client-side code — API keys should only be used in server-to-server calls.
5. Store keys securely — Use environment variables or a secrets manager, not code repositories.
6. Monitor usage — Check the "Last Used" column regularly to spot inactive or unexpected usage.

Rate Limits

External endpoints have a 60-request-per-minute route throttle in addition to the tenant's daily plan quota.

Successful API responses include X-RateLimit-Limit and X-RateLimit-Remaining. Exceeding the daily quota returns 429 with a Retry-After header. The daily counter resets at midnight UTC.

Authentication Errors

See Errors & Troubleshooting for more details.