Skip to main content

​
Authentication

All API requests must be authenticated. Yativo supports two authentication methods:
  • Bearer tokens — obtained via the magic-link flow or the API keys endpoint. Include in every request as Authorization: Bearer <token>.
  • Two-factor authentication (2FA) — optional TOTP-based 2FA for your account login. Enable it via the Authentication endpoints.
Tokens expire after a set period. Use GET /auth/refresh-token to get a new one without re-authenticating.

​
API key hygiene

  • One key per environment — use separate App Secrets for development, staging, and production so you can rotate or revoke one without affecting the others.
  • Never expose keys client-side — API credentials belong on your server. Do not embed them in mobile apps, browser JavaScript, or public repositories.
  • Rotate after suspected exposure — revoke your App Secret in the dashboard and generate a new one immediately if you believe it has been compromised.
  • Store in secrets managers — use environment variables or a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.), not plaintext config files.

​
Webhook signature verification

Always verify the X-Yativo-Signature header on incoming webhook requests. This prevents replay attacks and spoofed events.
Node.js
const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(hmac),
    Buffer.from(signature)
  );
}
Use crypto.timingSafeEqual (not ===) to prevent timing attacks.

​
HTTPS only

The Yativo API only accepts HTTPS connections. Webhook delivery also targets HTTPS endpoints only — HTTP URLs will be rejected on webhook creation.

​
IP allowlisting

For production environments, restrict outbound API calls to Yativo’s IP ranges and consider allowlisting inbound webhook IPs on your firewall. Contact support for the current list of Yativo webhook egress IPs.

​
Idempotency

For mutating requests (payouts, deposits, transfers), use the Idempotency-Key header to safely retry without risk of duplicate transactions: 
curl -X POST 'https://api.yativo.com/api/v1/sendmoney' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Idempotency-Key: your-unique-request-id-abc123' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
If a request with the same idempotency key succeeds, subsequent requests with that key return the original response without executing the operation again. Keys expire after 24 hours.

​
Rate limits

The API enforces rate limits per API key:
TierRequests per minute
Default120
Elevated600 (on request)
When a limit is hit, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry.

​
Sensitive data handling

  • Virtual card sensitive details (full PAN, CVV) are returned only on the card detail endpoint and should be displayed in-app temporarily — never logged or stored on your servers.
  • Yativo is PCI-DSS compliant. Do not log or store raw card data in your systems.
  • Customer PII (names, emails, phone numbers) should be treated as sensitive. Limit access in your systems to only those who need it.

​
Error responses

Security-related errors you may encounter:
HTTP statusMeaning
401 UnauthorizedMissing or invalid Bearer token / API key
403 ForbiddenValid credentials but insufficient permissions
429 Too Many RequestsRate limit exceeded
All error responses include a machine-readable code field: 
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired access token"
}