Authentication

EasySlip API uses HMAC-SHA256 signature authentication for secure API access.

HMAC Authentication

API v2 uses HMAC-SHA256 signature authentication for enhanced security. A single X-API-Key header is used for all endpoints — the key format determines the authentication flow:

Key Type	Format	Used For
Branch UUID	UUID v4 (e.g., a1b2c3d4-e5f6-...)	/verify/bank, /verify/truewallet, /info
B2B Client Key	64-char hex string	/b2b/* management endpoints

Required Headers

Header	Description
X-API-Key	Branch UUID or B2B Client hex key
X-Timestamp	Unix timestamp (seconds)
X-Nonce	UUID v4, unique per request
X-Signature	HMAC-SHA256 signature

How it works

• For verification/info endpoints: Use the branch UUID as X-API-Key. The server resolves the branch, finds the associated B2B client, and verifies the HMAC signature using the B2B client's secret key.
• For B2B management endpoints: Use the 64-character hex key as X-API-Key. The server looks up the B2B client directly.

In both cases, you sign the request with the same B2B client secret key.

For complete implementation details, code examples, and signature generation, see the B2B Authentication Guide.

Security Best Practices

1. Never Expose Keys in Client-Side Code

// ❌ BAD - Don't do this
const API_KEY = 'your-api-key-here';

// ✅ GOOD - Use environment variables
const API_KEY = process.env.EASYSLIP_API_KEY;

2. Use Environment Variables

.env

EASYSLIP_API_KEY=your-api-key-here

Node.js

import 'dotenv/config';

const apiKey = process.env.EASYSLIP_API_KEY;

PHP

$apiKey = getenv('EASYSLIP_API_KEY');
// or
$apiKey = $_ENV['EASYSLIP_API_KEY'];

Python

import os

api_key = os.environ.get('EASYSLIP_API_KEY')

3. Use Server-Side Requests Only

Always make API requests from your server, never from client-side JavaScript:

// ❌ BAD - Client-side request exposes your API key and secret
fetch('https://api.easyslip.com/v2/verify/bank', {
  headers: { 'X-API-Key': 'your-branch-uuid', 'X-Signature': '...' }
});

// ✅ GOOD - Make request through your own server
fetch('/api/verify-slip', {
  method: 'POST',
  body: JSON.stringify({ image: slipImage })
});

4. IP Whitelisting

Configure IP whitelisting in the developer portal to restrict API access to specific IP addresses:

1. Go to Application Settings
2. Add your server's IP addresses to the whitelist
3. Use * to allow all IPs (not recommended for production)

Authentication Errors

Missing API Key (401)

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header is required"
  }
}

Solution: Include the X-API-Key header in your request.

Invalid API Key (401)

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Solution: Check that your API key is correct and hasn't been revoked.

IP Not Allowed (403)

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address is not in the allowed list"
  }
}

Solution: Add your server's IP to the whitelist in the developer portal.

Branch Inactive (403)

{
  "success": false,
  "error": {
    "code": "BRANCH_INACTIVE",
    "message": "This API branch has been deactivated"
  }
}

Solution: Reactivate your branch in the developer portal or contact support.

Quota Exceeded (403)

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Your API quota has been exceeded"
  }
}

Solution: Upgrade your plan or wait for quota reset.

Multi-Branch Support

EasySlip supports multiple branches per application, each with its own API key:

• Main Branch: Primary API key with full quota
• Sub-Branches: Additional keys with separate quota tracking

This allows you to:

• Track usage per integration point
• Apply different IP restrictions per branch
• Manage quota allocation across teams

Next Steps

• B2B Authentication - HMAC authentication details
• API v2 Reference - Explore v2 endpoints
• Error Codes - Full error code reference