---
agentTools:
  projectIndex: https://suregifts-business-api.readme.io/llms.txt
---

# Integration Guide

# 1. Authentication

* **Public Key** → `username` in Basic Auth.
* **Secret** → `password` in Basic Auth.
* Combine as `PUBLIC_KEY:SECRET`, Base64 encode, then include in header:

```http
Authorization: Basic BASE64(PUBLIC_KEY:SECRET)
```

* Never expose keys in version control or client-side code.

# 2. Environments

## Test Environment

* **URL:** `https://staging-onlinebusiness.suregifts.com`
* Use for development and integration testing.

## Live Environment

* **URL:** `https://onlinebusiness.suregifts.com`
* Use only after successful testing in Test environment.

**.env Template:**

```ini
# Test
SG_ENV=test
SG_BASE_URL=https://staging-onlinebusiness.suregifts.com
SG_PUBLIC_KEY=pk_test_********************************
SG_SECRET=sk_test_********************************

# Live
# SG_ENV=live
# SG_BASE_URL=https://onlinebusiness.suregifts.com
# SG_PUBLIC_KEY=pk_live_********************************
# SG_SECRET=sk_live_********************************
```

# 3. Allowed IPs

The SureGifts API requires requests to come from approved IP addresses. You can provide **IPv4** or **IPv6** addresses in any of these formats:

**Accepted formats**

```text
# Single IP address
203.0.113.10
2001:db8::1

# Range using CIDR notation
198.51.100.0/25
2001:db8:1234::/48

# Multiple IPs or ranges (comma-separated)
203.0.113.10, 198.51.100.0/25, 2001:db8:1234::/48
```

**Steps to Configure**

1. Log in to your [SureGifts Business Dashboard](https://business.suregifts.com.ng/)
2. Go to **Developer > Allowed IPs**.
3. Enter your public outbound IP(s) or CIDR ranges in the accepted format above.
4. Click **Save** to apply.

**Notes**

* Prefer **static public egress IPs** from your hosting or network provider.
* Use the **narrowest CIDR range** that still covers all your outbound IPs.
* If behind NAT, whitelist the **public egress IP** visible to the internet.
* Avoid `0.0.0.0/0` or `::/0` except for short-term troubleshooting.
* If using multiple data centers or cloud regions, include all egress IPs.
* CIDR suffix `/X` indicates the number of fixed bits; e.g., `/24` for IPv4 covers 256 addresses.

# 4. Security Best Practices

* Rotate keys quarterly or on suspicion of compromise.
* Restrict dashboard access (least privilege + MFA).
* Keep logs secure; redact sensitive data.
* Always use HTTPS.

# 5. Go-Live Checklist (Pre-Checked)

* ✅ Test all API endpoints in the Test environment (happy paths + error paths)
* ✅ Confirm correct Base URL and API keys are set from environment variables
* ✅ Ensure Allowed IPs are restricted to secure locations; validate from the actual egress IPs
* ✅ Implement robust error handling, retries with backoff, and timeouts
* ✅ Centralize structured logging (requestId, endpoint, latency, status) and redact secrets
* ✅ Add health checks and alerting for elevated error rates and latency
* ✅ Document runbooks for key rotation and IP updates
* ✅ Review least-privilege access to dashboard and secrets store

# 6. Resilience Recommendations

* Timeouts: 10–30s (shorter for GETs)
* Retry policy: Exponential backoff with jitter
* Idempotency: Use request IDs for safe retries on writes

# 7. Governance & Ops

* Track changes to URLs, keys, and IPs with timestamps
* Emit metrics for requests, latency, and errors
* Securely back up non-secret configuration
* Maintain disaster recovery plans