Security Considerations

Overview

This guide covers the security requirements and best practices for integrating with the Cybrid
platform. Each section is organized into Required items that you must implement and Strongly
Recommended items that reduce risk.

For authentication details, see Token Scopes. For
webhook implementation, see the Webhooks guide.

Transport Security

Required

❗️

All communication with the Cybrid API must occur over HTTPS/TLS 1.2 or higher

This is a security requirement.

The Cybrid platform enforces SSL for all OAuth redirect URIs in production. Your application must enforce HTTPS for:

• All API requests to Cybrid endpoints
• All webhook receiving endpoints
• Any redirect URIs registered with your OAuth application

Strongly Recommended

• Certificate pinning: For mobile applications or high-security environments, consider pinning the
  Cybrid API's TLS certificate to prevent man-in-the-middle attacks.
• HSTS headers: Configure your webhook endpoints with HTTP Strict Transport Security headers.

API Credentials

Required

Embedding client IDs or secrets in your code repo increases the risk that those keys are compromised.

❗️

Store the client ID and client secret server-side

This is a security requirement.

Strongly Recommended

• Store the Client ID and Client Secret in environment variables in your build environment, using a secrets management
  tool such as AWS Secrets Manager,
  HashiCorp Vault, or
  Google Cloud Secret Manager.
• Store the keys in an encrypted fashion, instead of plain text. This reduces the risk of a key being copied and used.
• Restrict access to the Client ID and Secret to only certain people who must have access to
  configure the deployment or environment.
• Configure an IP allowlist on each production Application to limit the
  blast radius if credentials leak. Pin the allowlist to your server egress
  IPs (for example, a NAT gateway or fixed range) and validate the
  configuration on a non-production Application first — the new restriction
  takes effect on the next token issuance. An IP allowlist complements, but
  does not replace, the secrets-storage practices above. For the full
  walkthrough, see
  API Keys.

Token Handling

Required

Using a bank token with all authorization scopes allows executing API requests on the wrong
customer in the Cybrid Platform.

❗️

Generate customer-scoped access tokens for customer-based API requests

This scopes the API request to that customer only. This is a security requirement.

For example, when executing a trade for a customer, use a customer-scoped access token for this API
request instead of a bank token.

Use the POST /api/customer_tokens endpoint
in the Identity API to create customer tokens.

The Cybrid API grants access to resources through an Authorization Scope system. Read more about
scopes in Token Scopes.

❗️

Never expose access tokens to client-side code

Access tokens must never be exposed to browser JavaScript or mobile app local storage unless
using customer-scoped tokens intended for that purpose. This is a security requirement.

Bank and organization tokens carry broad privileges and must remain server-side. Only
customer-scoped tokens, with appropriately restricted scopes, should be used in client-facing
contexts.

Strongly Recommended

• When creating customer-scoped access tokens, take a least privilege approach when specifying
  authorization scopes. For example, if you're retrieving information such as trades for a customer,
  a customer-scoped access token with only the read scope would be the least restrictive while still
  providing access to the information.
• Never log tokens: Configure your application's logging framework to filter out authorization
  headers and token values.
• Token storage: Store tokens in memory when possible. If persistence is required, use encrypted
  storage mechanisms — never plain text files or unencrypted databases.
• Token scope separation: Use different tokens for different operations. For example, use a
  read-only scoped token for listing operations and a separate write-scoped token for executing
  trades or transfers.
• Handle token expiration: Access tokens have a default lifetime of 30 minutes in production and 8
  hours in sandbox (check the expires_in attribute in the token response). Implement retry logic
  that detects 401 Unauthorized responses and automatically requests a fresh token before retrying.

Customer tokens do not support refresh tokens. When a customer token expires, call
POST /api/customer_tokens again using your
bank token to generate a new one.

Customer Authentication

Required

❗️

Implement multi-factor authentication on customer account creation

This is a security requirement.

❗️

Implement multi-factor authentication on all customer transactions

This is a security requirement.

Strongly Recommended

• Verify the customer's email address on account creation.
• Implement multi-factor authentication on subsequent logins after account creation.

Webhook Security

Required

❗️

Validate the X-Cybrid-Signature header on all incoming webhook payloads

Use the signing key associated with your subscription. This is a security requirement.

The Cybrid platform signs all outbound webhook payloads with HMAC-SHA256 using your subscription's
signing key. You must verify this signature before processing any webhook event to prevent:

• Spoofed webhook events from unauthorized sources
• Tampered payloads modified in transit

⚠️

Constant-time comparison

Always use constant-time comparison when verifying signatures (e.g., hmac.compare_digest() in
Python, crypto.timingSafeEqual() in Node.js). Naive string equality (=== or ==) creates
vulnerability to timing attacks.

For signature verification code examples (JavaScript, Python) and the full webhook lifecycle, see
the Webhooks guide.

Strongly Recommended

• Implement replay attack protection by tracking webhook event IDs and rejecting duplicates.
• Implement timestamp validation — reject webhook payloads with timestamps older than a reasonable
  window (e.g., 5 minutes) to prevent replay of intercepted requests.
• Process webhooks idempotently — your handler should produce the same result if the same event is
  delivered more than once.
• Return a 2xx response quickly and process the webhook asynchronously. Long-running synchronous
  handlers risk timeouts and retries.

Browser Integration Security

Required

❗️

Configure your CORS allowed origins list to include only your specific domains

If you operate a browser-based application integrating with the Cybrid API, this is a security requirement.

Restrict your bank's cors_allowed_origins to the exact domains that need to make cross-origin
requests to the Cybrid API.

Add or allowlist CORS domains for a bank

To add or update the CORS allowed origins for a bank, use the Patch Bank endpoint. This specifies
which domains are permitted to make cross-origin requests to the Cybrid API.

Send a PATCH request to
/api/banks/{bank_guid} with a bearer token that
carries the banks:write scope, scoped to the organization or bank.

PATCH /api/banks/{bank_guid}
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{"cors_allowed_origins": ["https://yourdomain.com", "https://app.yourdomain.com", "http://localhost:3000"]}

{"guid": "bank_guid", "name": "Example Bank", "type": "sandbox", "cors_allowed_origins": ["https://yourdomain.com", "https://app.yourdomain.com", "http://localhost:3000"]}

The response returns the updated bank object, including the new cors_allowed_origins array
confirming your changes.

Key behavior:

• cors_allowed_origins is an array of allowed origin URIs (maximum 50 entries).
• The array you provide replaces the existing list entirely, so include every domain you want
  allowlisted. Omit the field to leave the current list unchanged, or send an empty array ([]) to
  clear it.
• Every origin must be a valid https:// URI. Plain http:// is rejected, with one exception:
  http://localhost (any port, for example http://localhost:3000) is allowed for local
  development. Origins such as http://yourdomain.com or http://127.0.0.1:3000 are rejected.
• Use full origin URLs including the protocol, for example https://app.yourdomain.com.
• Invalid or non-HTTPS origins return the error: CORS allowed origins must all be valid HTTPS URIs.

Strongly Recommended

• Content Security Policy: Implement CSP headers on your web application that restrict which domains can be contacted.
• Avoid wildcard origins: Never request wildcard CORS configurations. Each allowed origin should be
  a specific, fully-qualified domain.
• Subresource integrity: If loading any Cybrid-provided JavaScript resources, use SRI hashes to verify integrity.

Data Protection

Required

❗️

Encrypt all personally identifiable information (PII) received from the Cybrid API at rest in your systems

This is a security requirement.

The Cybrid platform encrypts all PII at the field level (names, addresses, dates of birth, phone
numbers, email addresses, identification numbers). Retrieving this data transfers responsibility
for its protection to your system.

For details on accessing PII via the API, see the
PII and IDV Documents guide.

Strongly Recommended

• Minimize PII retention: Only store PII that your application requires. Use the Cybrid API as the
  system of record and query it as needed rather than caching PII locally.
• Access logging: Log all access to PII fields with the accessing user or service identity for audit purposes.
• Data classification: Classify data received from the Cybrid API according to sensitivity and
  apply appropriate storage and access controls for each classification level.
• Secure deletion: When PII is no longer needed, securely delete it from your systems, including backups and logs.

Rate Limiting and Resilience

Strongly Recommended

• Implement client-side rate limiting: Even though the Cybrid API enforces rate limits at the
  infrastructure level, your integration should track its own usage to avoid hitting API limits
  during peak usage.

The default rate limit is 100 requests per IP address every 5 minutes. For details, see the
sandbox environment differences guide.

Token generation endpoints (/oauth/token and /oauth/customer_token) have separate rate limits
that return 403 Forbidden when exceeded — not the standard 429 Too Many Requests — so do not
confuse this with an authorization error. For details, see
Token Scopes.

• Exponential backoff: Implement exponential backoff with jitter for retries on 429 Too Many Requests or 5xx errors.
• Circuit breaker pattern: For production integrations, implement a circuit breaker to degrade when
  the Cybrid API is experiencing issues, rather than flooding the API with retry attempts.
• Timeouts: Set appropriate HTTP request timeouts (recommended: 30 seconds for standard
  operations). Do not use infinite timeouts.

Error Handling

Strongly Recommended

• Do not expose raw API errors to end users: Cybrid API error responses may contain internal
  identifiers, error codes, and diagnostic information. Map these to user-friendly messages in your
  application.
• Log errors securely: When logging Cybrid API errors for debugging, filter sensitive request and
  response data. The Cybrid platform returns standardized error codes (message_code) — log these
  rather than full response bodies.

Audit and Monitoring

Strongly Recommended

• Log all API interactions: Maintain audit logs of all API calls made to the Cybrid platform,
  including the endpoint, timestamp, token type used (bank vs. customer), and response status code.
  Exclude sensitive headers and bodies.
• Monitor for anomalies: Set up alerts for unusual patterns such as:
  • Unexpected spikes in API call volume
  • API calls from unexpected IP addresses or geographies
  • Failed authentication attempts
  • Customer token creation for customers who are not actively using your application
• Incident response plan: Have a documented plan for responding to credential compromise, including
  steps to rotate credentials and revoke existing tokens.