Skip to main content

​
Authentication

All PromoStack API requests require authentication using an API key.

​
Getting Your API Key

  1. Log in to PromoStack Dashboard
  2. Navigate to your app settings
  3. Copy your API key from the “API Keys” section
Keep your API key secure. Never commit it to version control or expose it in client-side code.

​
Using Your API Key

Include your API key in the x-api-key header of every request: 
curl -X POST https://api.promostack.app/referrer \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"uid": "user_123"}'
That’s it! No additional authentication headers needed. The API Gateway will handle the rest.

​
Security Best Practices

Use environment variables or secure key management systems. Never hardcode keys in your app.
// iOS - Use Info.plist or Keychain
let apiKey = Bundle.main.object(forInfoDictionaryKey: "PROMOSTACK_API_KEY")

// Android - Use BuildConfig or encrypted SharedPreferences
val apiKey = BuildConfig.PROMOSTACK_API_KEY
Generate new API keys periodically and update your app. Old keys can be revoked in the dashboard.
Track API usage in the dashboard to detect unusual patterns or potential key leaks.

​
Error Responses

​
401 Unauthorized

Missing or invalid API key: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
403 Forbidden

Valid key but insufficient permissions: 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have access to this resource"
  }
}

​
API Key Scopes

All API keys have full access to:
  • Referrer endpoints (/referrer, /referrer-claim)
  • Referee endpoints (/referee-redeem)
  • Webhook endpoints (read-only)
Custom scopes and read-only keys are available on Pro and Enterprise plans.