SECURITY & ACCESS CONTROLAuthentication & Permissions

API Authentication & Granular Permissions

Softymize provides enterprise-grade multi-tenant API security. Every request is verified using SHA-256 hashed secret keys, Shiprocket-style granular module permission scopes, static IP whitelisting, and Origin Domain Locking to guarantee 100% data isolation.

SHA-256 Key HashingPublic & Secret Key PairIP & Domain WhitelistingMulti-Tenant Scoped

Obtaining Your API Credentials

API keys are created and managed directly inside your Softymize Workspace Console:

1. Navigate to Settings

Log into Softymize Console and open Settings > API & Webhooks.

2. Generate Key Pair

Click Generate New API Key. Enter a descriptive key label (e.g. "Shopify Checkout Production") and select module scopes.

3. Save Your Secret Key

Copy and safely store your API Secret Key. Softymize only hashes and stores the SHA-256 hash in our database; the raw secret is never displayed again.

Protect Your Secret Keys:

Never commit Secret Keys (sft_live_sk_...) into client-side JavaScript, mobile app binaries, or public GitHub repositories. Use server-side environment variables or Next.js API route handlers to proxy external requests.

Supported Authentication Methods

Softymize offers flexible authentication schemes depending on your programming language and HTTP client architecture:

Single Secret Key Header (Recommended)

Standard

Pass your Secret Key directly in the X-Softymize-API-Key request header:

Method 1: X-Softymize-API-Key HeaderBash

curl -X POST https://api.softymize.com/api/v1/whatsapp/send \
  -H "X-Softymize-API-Key: sft_live_sk_9a8b7c6d5e4f3a2b10987654321fedcba0987654321" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "template_name": "order_confirmation_v2"}'

Bearer Token Header

OAuth / RFC 6750

Pass your Secret Key inside the standard HTTP Authorization: Bearer <key> header:

Method 2: Bearer TokenBash

curl -X POST https://api.softymize.com/api/v1/whatsapp/send \
  -H "Authorization: Bearer sft_live_sk_9a8b7c6d5e4f3a2b10987654321fedcba0987654321" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "template_name": "order_confirmation_v2"}'

Dual Key Pair (Public Key & Secret Key)

Enterprise

Send your Public Client ID (X-Softymize-Public-Key) and Private Secret Key (X-Softymize-Secret-Key) simultaneously for multi-layer validation:

Method 3: Dual Key Pair HeadersBash

curl -X POST https://api.softymize.com/api/v1/whatsapp/send \
  -H "X-Softymize-Public-Key: sft_live_pk_4a2b9c8d1e" \
  -H "X-Softymize-Secret-Key: sft_live_sk_9a8b7c6d5e4f3a2b10987654321fedcba0987654321" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "template_name": "order_confirmation_v2"}'

HTTP Basic Authentication

cURL -u

Use standard HTTP Basic Auth passing your Public Key as the username and Secret Key as the password:

Method 4: HTTP Basic AuthBash

curl -X POST https://api.softymize.com/api/v1/whatsapp/send \
  -u "sft_live_pk_4a2b9c8d1e:sft_live_sk_9a8b7c6d5e4f3a2b10987654321fedcba0987654321" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "template_name": "order_confirmation_v2"}'

Granular Permission Scopes (Module Access)

Softymize enforces Shiprocket-style granular permission scopes. When creating an API key, assign only the necessary permissions required for your integration. If an API key attempts an action outside its assigned scopes, the gateway returns 403 FORBIDDEN_SCOPE.

Permission Scope	Protected Endpoints	Purpose & Description
whatsapp:send	POST /api/v1/whatsapp/send	Dispatch Meta WhatsApp templates, order receipts, OTP verification, and media.
email:send	POST /api/v1/email/send	Dispatch transactional and marketing emails via AWS SES ingress engine.
sms:send	POST /api/v1/sms/send	Dispatch transactional SMS messages and telecom DLT fallback alerts.
otp:send	POST /api/v1/otp/send	Dispatch time-critical authentication OTPs across WhatsApp, Email, or SMS.
events:ingest	POST /api/v1/events	Ingest e-commerce and business lifecycle events (order created, abandoned cart, leads).
events:read	GET /api/v1/events	Query and audit historical ingested events, delivery status, and timestamps.
webhooks:manage	POST, GET, DELETE /api/v1/webhooks	Create, list, and delete real-time outgoing webhook subscription URLs.
contacts:create	POST /api/v1/contacts	Safely ingest customer contact profiles and attributes from your checkout.

Customer Privacy Protection: Bulk reading, scraping, or exporting entire customer CRM databases via API keys is strictly restricted (CONTACTS_READ_RESTRICTED). Contact exports can only be initiated by authenticated administrators inside the Softymize Console.

403 Forbidden Scope Error ResponseJSON

{
  "success": false,
  "error": {
    "code": "FORBIDDEN_SCOPE",
    "message": "API Key lacks required permission scope [whatsapp:send] to dispatch WhatsApp templates.",
    "doc_url": "https://docs.softymize.com/api-docs/authentication#scopes"
  }
}

Static IP Whitelisting

For enhanced production security, you can bind an API key to a comma-separated list of allowed server IP addresses (e.g. 198.51.100.4, 203.0.113.19).

Softymize inspects the client TCP origin IP address on every incoming request.
If an API request originates from an unlisted IP, the gateway immediately terminates the connection with 403 FORBIDDEN_IP.
Set to * or leave blank to allow requests from any IP (recommended for serverless environments like AWS Lambda or Vercel Edge).

Store Domain & Origin Security

To protect client-side checkouts and webhooks, Softymize workspaces enforce Origin Domain Locking.

Domain Whitelist Rules

In Softymize Workspace (Settings > Allowed Domains), add your production website domain (e.g. mybrand.com).
Wildcard subdomains are fully supported (e.g. *.mybrand.com will match checkout.mybrand.com, store.mybrand.com).
The gateway checks both Origin and Referer HTTP headers. Requests originating from unauthorized hostnames are rejected with 403 FORBIDDEN_DOMAIN.

Multi-Tenant Workspace Scoping

Every API key is mathematically tied to your specific workspace_id. Softymize automatically enforces strict tenant boundary isolation:

If your backend transmits an explicit workspace_id in the payload or via the X-Workspace-Id header, Softymize verifies that it matches the authenticated key's tenant:

Mismatched workspace IDs are immediately rejected with 403 MISMATCHED_WORKSPACE.

Authentication Error Codes Dictionary

Error Code	HTTP Status	Description & Resolution
UNAUTHENTICATED	401	Missing, invalid, or revoked API key. Verify header spelling and ensure you are sending your Secret Key (`sft_live_sk_...`).
FORBIDDEN_SCOPE	403	The API key does not have permission for the requested endpoint. Update permissions in Settings > API & Webhooks.
FORBIDDEN_IP	403	The caller's IP address is not included in the key's allowed IP whitelist.
FORBIDDEN_DOMAIN	403	The request's `Origin` or `Referer` header does not match your workspace allowed domains list.
API_KEY_DISABLED	403	The API key has been paused or deactivated in the dashboard.
PLAN_UPGRADE_REQUIRED	403	External REST API access requires a Growth or Pro plan. Upgrade in Settings > Billing.

← Introduction & Core Concepts WhatsApp API Reference →