Account & Authentication

This page summarizes frequently asked questions about account management and API authentication.

How to register a SUNBAY developer account?

Contact SUNBAY sales team or account manager
Submit company information and business scenario description
Provide relevant qualification materials as required
Wait for review (usually 1-3 business days)
After approval, you will receive an email with Copilot login information

Click “Forgot Password” on the login page
Enter your registered email
Check your email for password reset instructions
Click the link in the email to set a new password
Log in with the new password

If you don’t receive the email:

Check your spam folder
Confirm the email address is correct
Contact technical support

How to modify account information?

Log in to Copilot portal
Go to “Account Settings”
Modify the information you need to update
Save changes

API Keys

How to get API keys?

API keys need to be set by developers themselves:

Log in to Copilot portal
Go to “Developer” → “Application List”
Select your application
Go to “Payment integration” tab
In the “Security Key” area, set or view API keys, click “Show Secret” to view the complete key

Important Notes:

Keep them safe and don’t share with others
Don’t commit keys to code repositories

What if I forget my API key?

You can view it again in Copilot, but secondary authentication is required for security:

Log in to Copilot portal
Go to application details page → “Payment integration” tab
Click “Show Secret” in the “Security Key” area
Complete secondary authentication to view the key

How to rotate API keys?

For security, it’s recommended to rotate API keys regularly (every 90 days):

Log in to Copilot portal
Go to application details page → “Payment integration” tab
Regenerate keys in the “Security Key” area
The system supports key rotation; old keys will be retained for a period to avoid affecting production transactions during the switch
Gradually switch to new keys in your application
After confirming no issues, old keys will automatically expire

API Authentication

What to do if authentication fails?

Common causes of authentication failure:

1. API Key Error

Check if using the correct API Key
Confirm environment (sandbox/production) matches
Confirm API Key format is correct: Bearer {your_api_key}

2. Request Header Format Error

Confirm Authorization header format: Authorization: Bearer {your_api_key}
There must be a space between Bearer and API Key
Check for typos (Authorization not Authorisation)

3. Timestamp Issues

Check timestamp format (Unix timestamp, milliseconds, 13 digits)
Confirm server time is accurate
Time deviation cannot exceed ±10 minutes

4. Request ID Issues

Confirm X-Client-Request-Id format is correct (recommend using UUID)
Each request must use a unique Request ID
POST requests: Same ID within 10 minutes will be identified as duplicate request

Debugging Suggestions:


// Check request headers
console.log('Authorization:', headers['Authorization']);
console.log('X-Client-Request-Id:', headers['X-Client-Request-Id']);
console.log('X-Timestamp:', headers['X-Timestamp']);

What to do if timestamp validation fails?

Timestamp validation failure is usually because:

1. Server Time Inaccurate


# Linux/Mac sync time
sudo ntpdate -u time.nist.gov
 
# Windows sync time
w32tm /resync

2. Timestamp Format Error


// ✅ Correct - Unix timestamp (milliseconds, 13 digits)
const timestamp = Date.now();
 
// ❌ Wrong - seconds (10 digits)
const timestamp = Math.floor(Date.now() / 1000);

3. Time Deviation Too Large

Allowed time deviation: ±10 minutes
Check if request was delayed in sending
Check if using cached timestamp

How to configure IP whitelist?

Log in to Copilot portal
Go to application details page → “Payment integration” tab
Add allowed IP addresses in the “IP Whitelist” configuration area
Supports adding multiple IP addresses
Click “Add” to add to whitelist

Notes:

Takes effect immediately after configuration
IPs not in whitelist will be rejected
Recommend adding multiple IPs to prevent single point of failure

How to test API authentication?

Test using cURL:


# Set variables
API_KEY="your_api_key"
REQUEST_ID=$(uuidgen)
TIMESTAMP=$(date +%s%3N)  # Millisecond timestamp
REQUEST_BODY='{"amount":10000,"priceCurrency":"USD"}'
 
# Send request
curl -X POST https://open.sunbay.us/v1/semi-integration/transaction/sale \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: ${REQUEST_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -d "${REQUEST_BODY}"