Skip to main content

​
Credential management

​
Never expose secrets

These values must never appear in logs, source control, client-side code, or error messages:
  • Stellar seeds (S...)
  • API keys
  • Connect secrets
  • Webhook secrets
  • Bearer tokens (idToken, refreshToken, access_token)
  • OTP codes and session IDs

​
Store secrets securely

Use a cloud secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, GCP Secret Manager) or encrypted environment variables. Never hardcode credentials in your application.

​
Rotate regularly

  • Rotate API credentials via POST /v1/application/{id}/rotate-credential
  • Rotate webhook secrets via POST /v1/application/{id}/webhook/{webhookId}/rotate-secret
  • Both endpoints provide an overlap period for zero-downtime rotation

​
Transport security

  • HTTPS only — the production API requires TLS. Plain HTTP connections are rejected.
  • TLS 1.3 — the Go SDK enforces TLS 1.3 as the minimum version.
  • Certificate pinning — optionally pin root CAs using zeam.WithPinnedRootCAs() in the Go SDK.

​
Authentication security

  • Keep Stellar seeds server-side — never send seeds to a browser or mobile app. Use the two-step Ed25519 flow where the seed stays in your server’s memory.
  • Validate token expiry — refresh tokens proactively before they expire.
  • Use the right auth method — Ed25519 for backend services, OTP for user sign-in, OAuth for mobile/web apps.

​
Webhook security

  • Verify every delivery — compute HMAC-SHA256 over the raw body and compare using constant-time comparison.
  • Reject unverified payloads — never process a webhook without signature verification.
  • Handle replay attacks — use timestamp validation or event IDs for deduplication.

​
API usage

  • Never retry non-idempotent requests blindly — a POST that returned 200 may have been processed. Check status before retrying.
  • Capture X-Request-Id — include it in logs and error reports for fast triage.
  • Implement rate limit handling — respect 429 responses and Retry-After headers.

​
Reporting vulnerabilities

If you discover a security vulnerability, report it privately to [email protected]. Do not open a public issue.