Authentication

All API requests must be authenticated using your API key. Salam uses API keys to control access and identify your account.

API Keys

You can view and manage your API keys in the Dashboard.

Key Types

Key Type	Prefix	Use Case	Scope
Secret Key	sk_test_ / sk_live_	Server-side requests	Full API access
Publishable Key	pk_test_ / pk_live_	Client-side (browser)	Limited operations

Security Warning

Your secret key can perform any API operation on your account, including processing payments and refunds. Keep it secure:

• Never expose it in client-side code
• Don't commit it to version control
• Use environment variables
• Rotate keys if compromised

Using API Keys

Bearer Token (Recommended)

Include your API key in the Authorization header with the Bearer prefix:

curl https://api.salam.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxx" \
  -H "Content-Type: application/json"

SDK Usage

Node.js

const Salam = require('@salam/salam-node');
const salam = new Salam('sk_test_xxxxx');

// Or with options
const salam = new Salam('sk_test_xxxxx', {
  apiVersion: '2024-01-01',
  timeout: 30000, // 30 seconds
});

Browser (JavaScript)

// Use publishable key only
const salam = Salam('pk_test_xxxxx');

// Never use secret key in browser
// ❌ const salam = Salam('sk_test_xxxxx'); // DANGEROUS!

Environments

Environment	API Base URL	Dashboard Mode
Test	https://api.salam.com	Test mode toggle
Live	https://api.salam.com	Live mode toggle

Both environments use the same API URL. The environment is determined by your API key prefix (test vs live).

Key Rotation

If you believe your secret key has been compromised:

1. Go to Dashboard → Developers → API Keys
2. Click "Roll Key" on the compromised key
3. A new key will be generated immediately
4. Update your application with the new key
5. The old key will be invalidated after 24 hours

Grace Period

During the 24-hour grace period, both old and new keys work. This allows you to update your application without downtime.

Rate Limits

Salam enforces rate limits to ensure API stability and fair usage:

Endpoint	Rate Limit	Time Window
All endpoints	100 requests	per second
Payment creation	50 requests	per second
Refunds	30 requests	per second
Webhooks	No limit	-

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1704067200

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 1 second.",
    "retry_after": 1
  }
}

Retry Strategy:

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.type === 'rate_limit_error' && i < maxRetries - 1) {
        const retryAfter = error.retry_after || 1;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
}

// Usage
const payment = await makeRequestWithRetry(() =>
  salam.payments.create({
    amount: 10000,
    currency: 'MYR',
    payment_method: 'pm_xxxxx',
  })
);

IP Allowlisting (Optional)

For additional security, you can restrict API access to specific IP addresses:

1. Go to Dashboard → Developers → API Keys
2. Click on your key
3. Enable "IP Allowlisting"
4. Add IP addresses or CIDR ranges

# Example allowlist
203.0.113.0/24
198.51.100.42
2001:db8::/32

Webhook IPs

If using IP allowlisting, make sure to include your webhook server IPs. You can find Salam's webhook IP ranges in the Dashboard.

API Versioning

Salam uses date-based API versioning to ensure backward compatibility:

curl https://api.salam.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxx" \
  -H "Salam-Version: 2024-01-01"

In SDK:

const salam = new Salam('sk_test_xxxxx', {
  apiVersion: '2024-01-01',
});

Version History:

• 2024-01-01 - Current version
• 2023-12-01 - Previous version (deprecated)

Default Version

If no version is specified, the latest version is used. We recommend pinning a specific version in production.

Best Practices

✅ Do's

• Store API keys in environment variables
• Use different keys for different environments
• Rotate keys regularly (every 90 days)
• Implement exponential backoff for retries
• Use idempotency keys for safe retries
• Monitor your API usage in the Dashboard

❌ Don'ts

• Don't commit keys to version control
• Don't expose secret keys in client-side code
• Don't share keys between applications
• Don't hard-code keys in your application
• Don't ignore rate limit headers

Security Checklist

Before going to production:

• [ ] Secret keys stored in environment variables
• [ ] Different keys for test and live environments
• [ ] IP allowlisting enabled (optional but recommended)
• [ ] TLS 1.2+ enforced on your servers
• [ ] Webhook signature verification implemented
• [ ] Error handling for all API requests
• [ ] Rate limit handling implemented
• [ ] Monitoring and alerting set up

Testing Authentication

Test your authentication setup:

const Salam = require('@salam/salam-node');
const salam = new Salam('sk_test_xxxxx');

async function testAuth() {
  try {
    // This will throw an error if authentication fails
    const balance = await salam.balance.retrieve();
    console.log('✓ Authentication successful');
    console.log('Balance:', balance.available);
  } catch (error) {
    console.error('✗ Authentication failed:', error.message);
  }
}

testAuth();

Next Steps

• Test Mode - Learn about testing
• Quick Start - Create your first payment
• Webhooks - Set up event notifications
• Error Handling - Handle API errors properly