P
PUGUH
ID Get Started

Best Practices

Recommendations for using ARSAKA PUGUH effectively.

SDK Integration

Use Environment Variables

Never hardcode credentials in your application:

typescript 
// Bad: Hardcoded credentials
const client = new PuguhClient({
  baseUrl: 'https://api-puguh.arsaka.io',
});
await client.auth.login({ email: 'admin@company.com', password: 'secret123' });

// Good: Use environment variables
const client = new PuguhClient({
  baseUrl: process.env.PUGUH_API_URL,
});
await client.auth.login({
  email: process.env.PUGUH_EMAIL,
  password: process.env.PUGUH_PASSWORD,
});

Handle Token Refresh

Implement automatic token refresh to avoid session expiry:

typescript 
// The SDK handles refresh automatically, but check for errors
try {
  const orgs = await client.organizations.list();
} catch (error) {
  if (error.statusCode === 401) {
    await client.auth.refresh();
    // Retry the request
  }
}

Use Application Environments

  1. Create separate applications for development, staging, production
  2. Use different API keys per environment
  3. Test webhooks with development environment first
  4. Verify in staging before production

Organization

Use Application Structure

plaintext 
Organization: Acme Corp
  Application: production
    Webhooks (strict URLs only)
    Storage (encrypted)
  Application: staging
    Webhooks (test endpoints)
    Storage (relaxed limits)
  Application: development
    Webhooks (localhost OK)
    Storage (public access)

Webhook Best Practices

  • Always verify webhook signatures
  • Use HTTPS endpoints only
  • Implement idempotency in your webhook handler
  • Return 200 quickly, process asynchronously
  • Monitor delivery failures in the audit trail

Security

Principle of Least Privilege

  1. Start users as Viewers
  2. Upgrade to Member when needed
  3. Admin only for management
  4. Owner is singular

Audit Regularly

typescript 
// Weekly audit script
const entries = await client.control.listAudit({
  startDate: sevenDaysAgo,
  actions: ['user.role_changed', 'organization.settings_updated'],
});

for (const entry of entries.items) {
  console.log(`${entry.timestamp}: ${entry.actorEmail} - ${entry.action}`);
}

Monitor for Anomalies

Set up alerts for:

  • Unusual access patterns
  • Spike in failed requests
  • After-hours activity
  • Bulk operations

Secure API Keys

typescript 
// Use environment variables
const client = new PuguhClient({
  apiKey: process.env.PUGUH_API_KEY, // Never hardcode
});

// Rotate regularly
await client.rotateApiKey(keyId);

Performance

Use Pagination

Always paginate large result sets:

typescript 
// Bad: Fetch all at once
const all = await client.control.listAudit();

// Good: Paginate
const page1 = await client.control.listAudit({ page: 1, limit: 50 });
const page2 = await client.control.listAudit({ page: 2, limit: 50 });

Handle Rate Limits

typescript 
// Implement retry with backoff
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429 && i < maxRetries - 1) {
        await sleep(1000 * Math.pow(2, i));
        continue;
      }
      throw error;
    }
  }
}

Monitoring

Track Key Metrics

  • API response latency (P50, P95, P99)
  • Webhook delivery success rate
  • Authentication failure rate
  • Error rates by endpoint

Set Up Alerts

yaml 
alerts:
  - name: High API Latency
    condition: api.latency.p99 > 500ms
    duration: 5m
    notify: ops-team

  - name: Webhook Delivery Failures
    condition: webhook.failure_rate > 10%
    duration: 15m
    notify: dev-team

Review Regularly

Schedule regular reviews:

  • Daily: Check webhook delivery status, DLQ
  • Weekly: Review audit logs, usage metrics
  • Monthly: Analyze trends, optimize configurations
  • Quarterly: Security audit, role review

Related