Skip to main content

Security Best Practices

This guide covers security best practices for configuring your Carabaas organization, managing API access, and implementing duty segregation.

API Key Security​

Key Generation​

Generate RSA-4096 keys for maximum security:

openssl genrsa -out private_key.pem 4096
openssl rsa -in private_key.pem -pubout -out public_key.pem

Key Storage​

EnvironmentRecommended Storage
ProductionHSM (Hardware Security Module) or cloud KMS
StagingSecret manager (AWS Secrets Manager, Vault)
DevelopmentEncrypted local file

Key Rotation​

  1. Generate a new RSA key pair
  2. Register the new public key via the API
  3. Update your application to use the new private key
  4. Verify the new key works
  5. Block the old key
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
       "name": "Production API Key v2"
     }' \
     https://api.carabaas.com/api/v1/organizations/keys

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
     https://api.carabaas.com/api/v1/organizations/keys/{oldKeyId}/block

JWT Token Lifetime​

Set exp according to your security policy:

Use CaseRecommended Lifetime
Per-request tokens30 seconds
Session tokens1 hour
Service-to-service15 minutes

Role-Based Access Control​

Principle of Least Privilege​

Assign the minimum role needed for each user or API client:

TaskMinimum Role
View balances and txsViewer
Create transactionsOperator
Approve transactionsApprover
Manage vault settingsVaultAdmin
Manage organization usersOrgAdmin
Emergency suspensionSecurityOfficer

Segregation of Duties​

Ensure no single person can both initiate and approve a transaction:

RoleCan InitiateCan ApproveCan Sign
Operator✅❌❌
Approver❌✅❌
Signer❌❌✅
VaultAdmin✅✅❌
Treasurer✅✅❌

Suspend Compromised Clients​

If a client's credentials are compromised, suspend immediately:

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
     https://api.carabaas.com/api/v1/organizations/clients/{clientId}/suspend

Quorum Policies​

Design Principles​

  • Low-value vaults (hot wallets) — lower quorum (1-of-2 or automated)
  • High-value vaults (treasury, customer funds) — higher quorum (2-of-3 or 3-of-5)
  • Different approver pools — use separate groups for different risk levels
  • Automated vs. manual — API co-signers for automated approval, human approval for high-value

Example: Three-Tier Policy​

VaultQuorumApproversUse Case
Hot Operations1-of-2API + Ops LeadDaily withdrawals
Customer Funds2-of-3Compliance + Ops + FinanceCustomer payouts
Treasury3-of-5CEO + CFO + COO + CTO + CISOLarge movements

Cosigner Security​

Unseal Key Holder Selection​

Choose unseal key holders from different departments and different geographic locations:

  • Key Holder 1: Security team (Location A)
  • Key Holder 2: Operations team (Location B)
  • Key Holder 3: Executive team (Location C)

No single department or location compromise can unseal the cosigner.

Cosigner Monitoring​

Monitor the cosigner's status endpoint and alert on state changes:

StatusAlert LevelAction
readyNormalNone
sealedWarningContact unseal key holders
disconnectedCriticalInvestigate network/server issues

Security Checklist​

ItemStatus
RSA keys stored in HSM or secret manager☐
JWT lifetime set to minimum needed☐
API key rotation schedule defined☐
Roles follow least-privilege principle☐
Initiation and approval separated☐
Quorum policies match risk levels☐
Unseal key holders in separate departments☐
Cosigner monitoring and alerting active☐
Address book whitelisting enabled☐
Audit log export configured☐

See Also​