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.

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.

Configure your bank's cors_allowed_origins via PATCH /api/banks/{bank_guid} to include only the exact domains that need to make cross-origin requests to the Cybrid API. This endpoint requires a bank token with the banks:write scope.

All origins must be valid HTTPS URIs (maximum 50).

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.