Skip to main content
This manual outlines the security measures implemented in the Stellar Disbursement Platform (SDP) to protect the integrity of the platform and its users. By adhering to these guidelines, you can ensure that your use of the SDP is as secure as possible. Security is a critical aspect of the SDP. The measures outlined in this document are designed to mitigate risks and enhance the security of the platform. Users are strongly encouraged to follow these guidelines to protect their accounts and operations.

Implementation of reCAPTCHA

Google’s reCAPTCHA has been integrated into the SDP to prevent automated attacks and ensure that interactions are performed by humans, not bots. ReCAPTCHA is enabled by default and can be disabled by setting the DISABLE_RECAPTCHA environment variable to true. Configuration is available at two levels:
  1. Environment default – Set DISABLE_RECAPTCHA=true to apply the setting globally across all tenants.
  2. Tenant override – Each organization can enable or disable reCAPTCHA via its own settings (UI or API). When present, the tenant-level choice overrides the environment default.
Use the following environment variables to control how reCAPTCHA behaves:
  • CAPTCHA_TYPE – GOOGLE_RECAPTCHA_V2 (default) or GOOGLE_RECAPTCHA_V3.
  • RECAPTCHA_SITE_KEY – Google site key issued for the chosen CAPTCHA type.
  • RECAPTCHA_SITE_SECRET_KEY – Google secret key paired with the site key.
  • RECAPTCHA_V3_MIN_SCORE – Minimum allowed score (0.0–1.0, default 0.5) when CAPTCHA_TYPE=GOOGLE_RECAPTCHA_V3.
Note: Disabling reCAPTCHA in production (pubnet) deployments substantially reduces protection against automated abuse. This configuration should be used only when equivalent compensating controls are in place.

Enforcement of Multi-Factor Authentication

Multi-Factor Authentication (MFA) provides an additional layer of security to user accounts. It is enforced by default on the SDP and it relies on OTPs sent to the account’s email. MFA is enabled by default and can be disabled in the development environment by setting the DISABLE_MFA environment variable to true. Note: MFA cannot be disabled in production (pubnet) environments due to security risk.

Request Rate Limiting and Network Protections

SDP enforces rate limiting at the HTTP layer to curb scripted abuse. Each unique <IP, endpoint> pair is limited to 40 requests within 20 seconds (rolling window). Short registration links (/r/{code}) also enforce this limit per client IP across all codes and tenants. Requests that exceed this threshold receive throttled responses until the window resets.

Authentication and Authorization Models

All authenticated API routes require clients to present either an SDP-issued API key or a JWT derived from the SEP10/SEP24 flows. These two mechanisms run in parallel: JWTs are for interactive users, while API keys enable programmatic integrations with their own scoping model.

JWT Roles

JWTs represent human users that sign in through the UI. After authentication, the platform authorizes them based on the roles assigned to their user account. The primary roles are:
  • Owner – Full control, including creating users, assigning roles, and editing organization configuration. Owner is the only role that can grant or revoke access for others. Permissions apply to every distribution account.
  • Financial Controller – Can perform every operational task (wallets, assets, disbursements, statistics) except user management. This role is ideal for finance staff executing payouts.
  • Developer – Manages technical configuration such as wallets, assets, and API keys, and can view statistics; it cannot modify users or financial workflows. Permissions apply to every distribution account.
  • Business – Read-only across business data (disbursements, recipients, statistics) but cannot access user management details.
  • Initiator – Creates and saves disbursements but cannot submit them. Mutually exclusive with the Approver role to enforce separation of duties.
  • Approver – Reviews and submits disbursements but cannot create new ones; mutually exclusive with Initiator.
Each API endpoint specifies which JWT roles may access it—for example, API key management routes (/api-keys) require Owner or Developer, while disbursement creation requires Initiator or Financial Controller and submission requires Approver or Financial Controller. Deactivating a user ends their dashboard sessions. When the host deactivates or deletes a tenant, the same happens to all of that tenant’s users.

Distribution Account Access

Roles are tenant-wide and determine what a user may do. Access to a distribution account is granted separately, per account, and determines where they may do it. Both are required: a user who holds the right role but no access to an account cannot act on that account, and a user with access to an account cannot exceed what their role allows there. The Owner and Developer roles are the exceptions: they apply tenant-wide, cover every account, and are never given per-account access. Only Owners can grant or revoke access to accounts. Changing a user to Owner or Developer removes their per-account access. Changing an Owner or Developer to another role gives them access to the default account, and Owners can grant more. Owners manage per-distribution account access from Dashboard Home, choosing the role a user holds on that account. A user who has been given no account access can sign in but sees no disbursements, payments, or receivers.

API Key Permissions

API keys bypass JWT roles and instead embed their own permission scopes. When a request includes an API key, the middleware validates the key, confirms the caller’s IP address is allowed (if restricted), checks the expiration, and finally ensures the key contains the scopes required by the endpoint. API keys are typically used for automation and service-to-service integrations where precise read/write access is needed. Creating or rotating API keys requires an Owner or Developer role, or an API key with write:all. Available scopes map directly to the major SDP resources:
  • read:all, write:all
  • read:disbursements, write:disbursements
  • read:receivers, write:receivers
  • read:payments, write:payments
  • read:organization, write:organization
  • read:users, write:users
  • read:wallets, write:wallets
  • read:distribution_wallets, write:distribution_wallets
  • read:statistics
  • read:exports
  • read:reports
In addition to permissions, an API key can be restricted to acting on specific distribution accounts through the distribution_wallet_ids field. A key is judged only by its permissions and its account scope, whoever created it. Endpoints that act on one account (archive, promote to default, memberships) need that account in the key’s scope; promoting also needs the current default account in scope. An API key can only manage other API keys that were created by the same user and whose distribution-account scope is within its own. It cannot create a key scoped beyond its own accounts.

Selecting an Account

In the dashboard, the active distribution account that requests act on is chosen in the account picker. Integrations calling the API directly set the X-Wallet-Id header themselves. The header narrows what a request reaches and never widens it. A caller with access to three accounts that names one of them acts only on that one, and naming an account they have no access to reaches nothing. On reads the header is optional. If sent, results cover that account; omitted, they cover every account the caller has access to (what the dashboard’s “All accounts” view does). It is required on writes that send funds or create records against an account, since those must resolve to exactly one source account—unless the tenant has a single active account, or the API key is restricted to one. To enhance security, disbursement responsibilities should be distributed among multiple financial controller users.
  1. Approval Flow: Enable the approval flow on the organization page to require two users for the disbursement process. The owner can do that at Profile > Organization > … > Edit details > Approval flow > Confirm.
  2. Financial Controller Role: Create two users with the Financial Controller role on the organization page to enforce separation of duties. The owner can do that at Settings > Team Members.
  3. Owner Account Management: Use the Owner account solely for user management and organization configuration. Avoid using the Owner account for financial controller tasks to minimize the exposure of that account.

Best Practices for Wallet Management

The SDP wallet should be used primarily as a hot wallet with a limited amount of funds to minimize potential losses.

Hot and Cold Wallets

  • A hot wallet is connected to the internet and allows for quick transactions.
  • A cold wallet is offline and used for storing funds securely.
  • Learn more about these concepts at Investopedia.