Authorization

Authentication Model Overview

Springbig requires two sets of keys for all authenticated requests:

1. x-api-key – Partner Key
2. AUTH-TOKEN – Merchant Access Token

These keys work together to ensure:

• Partners are identified and authenticated at the platform level
• Merchants maintain full control over which integrations can access their account
• Access can be granted or revoked without impacting the partner’s global integration

x-api-key (Partner Key)

The x-api-key uniquely identifies the integration partner.

Key Characteristics:

• Issued once per environment (staging or production)
• Valid across all merchants the partner is authorized to access
• Used for every API call in that environment
• Should be securely stored and hardcoded server-side

Header Usage Example:

x-api-key: <partner_api_key>

AUTH-TOKEN (Merchant Key)

The AUTH-TOKEN provides request-level access to a specific merchant account.

Key Characteristics:

• Unique per merchant
• Represents the merchant’s authorization for the partner to access their data
• Required for all merchant-scoped endpoints (members, visits, messaging, loyalty, etc.)
• Can be rotated or revoked without affecting the partner’s x-api-key

Header Usage Example:

AUTH-TOKEN: <partner_api_key>

Key Issuance

Sandbox keys are issued when:

• The partner has completed the formal Partnership Agreement, and
• The merchant has authorized access to their account (if merchant-scoped testing is required)
• Developers use sandbox keys to build workflows, test payloads, and validate integrations without delivering real messages or modifying production data.

Production Keys

Production keys are issued after:

• Sandbox development is completed
• Both the partner and Springbig have verified the integration
• The merchant has formally granted access to their production account

Important Notes

Both headers (x-api-key and AUTH-TOKEN) are required for all authenticated Springbig API calls.

Missing or invalid keys will result in 401 Unauthorized or 403 Forbidden responses.

Never expose these keys client-side. Always secure them on your server.

If you need assistance obtaining sandbox or production keys, please contact us at [email protected]