Manage API Keys

Authentication

The SuiPay SDK uses API keys for authentication. This guide explains how to configure authentication in your application using the SDK.

SDK Authentication Setup

The SDK handles authentication automatically once you provide your API key during client initialization. No need to manually set headers or manage tokens.

import { SuiPayClient } from '@suipay/api';

const client = new SuiPayClient({
  apiKey: 'sk_your_api_key_here'
});

API Key Format

API keys are prefixed with sk_ and generated using cryptographically secure random bytes. A typical API key looks like:

sk_1234567890abcdef1234567890abcdef

Getting Your API Key

API keys should be created through the SuiPay dashboard:

1. Login to SuiPay: Visit https://demo2.suipay.net and sign in to your account

2. Navigate to Dev API Keys: Go to the "Dev API Keys" section in your dashboard

3. Create New API Key: Click "Create API Key" and give it a descriptive name

4. Copy and Store: Your API key will be shown once - copy it immediately and store it securely

Configuration Options

Basic Configuration

const client = new SuiPayClient({
  apiKey: 'sk_your_api_key_here'
});

Environment Variables

Use environment variables for better security:

// .env file
SUIPAY_API_KEY=sk_your_api_key_here
SUIPAY_BASE_URL=https://api.suipay.net/api/v1  // optional

// In your code
const client = new SuiPayClient({
  apiKey: process.env.SUIPAY_API_KEY!,
  baseUrl: process.env.SUIPAY_BASE_URL  // optional
});

Testing Authentication

Use the ping() method to verify your API key is working:

try {
  const result = await client.ping();
  if (result.success) {
    console.log(`✅ Authentication successful! User ID: ${result.user_id}`);
  } else {
    console.log('❌ Authentication failed');
  }
} catch (error) {
  console.error('Authentication error:', error);
}

User Access Control

API keys are scoped to specific users and their resources:

• Each API key can only access the user account it was created for

• You cannot access other users' data with your API key

• All resources (payment links, withdrawals, bank accounts) are tied to the user associated with your API key

Example access control:

1. API Key A is created for User 1

2. API Key B is created for User 2

3. API Key A can only access User 1's data and resources

4. API Key B can only access User 2's data and resources

Authentication Errors

The SDK provides specific error types for authentication issues:

import { SuiPayAuthenticationError } from '@suipay/api';

try {
  const user = await client.user.get();
} catch (error) {
  if (error instanceof SuiPayAuthenticationError) {
    console.error('Authentication failed:', error.message);
    // Possible causes:
    // - Invalid API key
    // - API key doesn't exist
    // - API key has been deactivated
  }
}

Common Authentication Errors

Error	Description	Solution
Invalid API key	API key format is incorrect	Ensure API key starts with sk_
API key not found	API key doesn't exist	Check your API key in the dashboard
API key deactivated	API key has been disabled	Create a new API key
Unauthorized	Missing or malformed API key	Verify client initialization

Security Best Practices

1. Environment Variables

// ✅ Good
const client = new SuiPayClient({
  apiKey: process.env.SUIPAY_API_KEY!
});

// ❌ Bad - hardcoded in source
const client = new SuiPayClient({
  apiKey: 'sk_1234567890abcdef...'
});

2. Separate Keys per Environment

// ✅ Good - separate keys
const config = {
  development: {
    apiKey: process.env.SUIPAY_DEV_API_KEY!,
    baseUrl: 'http://localhost:3001/api/v1'
  },
  production: {
    apiKey: process.env.SUIPAY_PROD_API_KEY!,
    baseUrl: 'https://api.suipay.net/api/v1'
  }
};

const client = new SuiPayClient(config[process.env.NODE_ENV!]);

3. Key Validation

function createSuiPayClient(apiKey: string) {
  if (!apiKey) {
    throw new Error('API key is required');
  }
  
  if (!apiKey.startsWith('sk_')) {
    throw new Error('Invalid API key format');
  }
  
  return new SuiPayClient({ apiKey });
}

4. Error Handling

async function initializeClient() {
  try {
    const client = new SuiPayClient({
      apiKey: process.env.SUIPAY_API_KEY!
    });
    
    // Test the connection
    const result = await client.ping();
    if (!result.success) {
      throw new Error('Failed to authenticate with SuiPay API');
    }
    
    return client;
  } catch (error) {
    console.error('Failed to initialize SuiPay client:', error);
    throw error;
  }
}

Best Practices Summary

1. Store API keys securely using environment variables

2. Never commit API keys to version control

3. Use different API keys for development and production

4. Test authentication before using the client

5. Handle authentication errors gracefully

6. Rotate API keys regularly

7. Monitor API key usage in the dashboard

8. Deactivate unused API keys promptly