Reward Agent Authentication

The Reward Agent uses HMAC-SHA256 signatures to authenticate requests for write operations and sensitive data access.

When Authentication Is Required

Public tools (27) — No authentication needed:

• Discovery (rsnc_agent_network_info, rsnc_agent_list_brands, rsnc_agent_check_brand, rsnc_agent_brand_rankings, rsnc_agent_network_stats)
• Brand (rsnc_agent_brand_info, rsnc_agent_brand_perks)
• Browse perks (rsnc_agent_browse_perks)
• Leaderboard (rsnc_agent_leaderboard)
• Growth (rsnc_agent_estimate_roi, rsnc_agent_request_info)
• Analytics (rsnc_agent_network_analytics, rsnc_agent_brand_analytics, rsnc_agent_event_performance, rsnc_agent_perk_analytics, rsnc_agent_brand_health)
• Comparison (rsnc_agent_compare_brands, rsnc_agent_compare_cashback)
• Commerce routing (rsnc_agent_route_purchase)
• Recommendations (rsnc_agent_best_deals)
• Intelligence (rsnc_agent_perk_intelligence, rsnc_agent_perk_audience, rsnc_agent_brand_audience)
• Network intelligence (rsnc_agent_network_flows, rsnc_agent_network_trending)
• Suggestions (rsnc_agent_suggest_events, rsnc_agent_suggest_perks)

Authenticated tools (18) — HMAC signature required:

Tool	Additional Permission
rsnc_agent_user_balance	—
rsnc_agent_user_stats	—
rsnc_agent_user_portfolio	—
rsnc_agent_process_event	—
rsnc_agent_process_bulk	—
rsnc_agent_redeem_perk	—
rsnc_agent_stack_deals	—
rsnc_agent_next_goal	—
rsnc_agent_my_rewards	—
rsnc_agent_claim_reward	—
rsnc_agent_user_persona	—
rsnc_agent_user_recommendations	—
rsnc_agent_onboard_brand	canOnboard
rsnc_agent_manage_keys	canOnboard
rsnc_agent_create_event	canManageProgram
rsnc_agent_update_event	canManageProgram
rsnc_agent_create_perk	canManageProgram
rsnc_agent_update_perk	canManageProgram

HMAC Signing Process

Step 1: Build the String to Sign

string_to_sign = timestamp + "\n" + method + "\n" + path + "\n" + SHA-256(body)

Component	Value
timestamp	Unix timestamp in seconds (e.g., 1709500000)
method	HTTP method, uppercase (e.g., POST)
path	Request path (e.g., /mcp)
SHA-256(body)	Hex-encoded SHA-256 hash of the request body

Step 2: Compute the Signature

signature = HMAC-SHA256(agent_api_secret, string_to_sign)

The result is hex-encoded.

Step 3: Send Request Headers

Header	Value
X-RSNC-Agent-Key	Your agent key ID
X-RSNC-Timestamp	The timestamp used in signing
X-RSNC-Signature	The hex-encoded HMAC-SHA256 signature

Example (Node.js)

import crypto from 'crypto';

function signRequest(method: string, path: string, body: string, secret: string) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const stringToSign = `${timestamp}\n${method}\n${path}\n${bodyHash}`;
  const signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('hex');

  return {
    'X-RSNC-Agent-Key': 'your-key-id',
    'X-RSNC-Timestamp': timestamp,
    'X-RSNC-Signature': signature,
  };
}

Validation Rules

• Timestamp window: Must be within 300 seconds (5 minutes) of server time
• Timing-safe comparison: Signature verification uses constant-time comparison
• Descriptive errors: Failed authentication returns specific error messages

API Key Structure

Each agent key has:

Field	Description
secret	API secret (encrypted with AES-256-GCM in database)
name	Display name for the key
brands	Authorized brands — ["*"] for all, or specific brand IDs
rateLimit	Per-key rate limit (default: 20 requests/minute)
permissions	Object with canOnboard and canManageProgram booleans

Permissions

canOnboard

Required for:

• rsnc_agent_onboard_brand — Register new brands on the network
• rsnc_agent_manage_keys — Rotate, revoke, or check API key status

canManageProgram

Required for:

• rsnc_agent_create_event — Create earning events
• rsnc_agent_update_event — Modify event configuration
• rsnc_agent_create_perk — Create perk collections
• rsnc_agent_update_perk — Modify perk configuration

Brand Scope

Keys can be scoped to specific brands:

• brands: ["*"] — Access all brands (for network-level agents)
• brands: ["0xABC..."] — Access only the specified brand

Key Management

Use rsnc_agent_manage_keys to manage API keys:

Action	Description
status	Check if key exists and its activation status
rotate	Generate a new secret (old secret is invalidated)
revoke	Disable the key entirely

Key Resolution

The agent resolves keys in this order:

1. Cloudflare KV cache (5-minute TTL for performance)
2. Supabase agent_keys table (encrypted secrets)
3. Legacy environment variable (fallback)

Next Steps

• Tools Reference — See which tools require auth
• Getting Started — Connect your AI assistant
• Examples — See authenticated tool examples