Skip to main content

Technical Details

In this section, you will find additional technical information about the brokerize API that is important for a robust and error-free integration.

👤 User Accounts & Integration​

  • Every API request is executed on behalf of an end user interacting with your application.
  • Recommended approach: Call the API directly from the frontend. This ensures your backend never handles access tokens or sensitive user data and does not send orders to brokers.
  • For web apps, this typically requires a CORS configuration that can easily be attached to your client configuration. If you believe you must call the API from your backend, please contact our support to discuss your use case and options.

Guest User Model​

All end users access the API as anonymous guest users. A new guest user can be created using the CreateGuestUser endpoint.

  • Guest users are temporary by default. Their lifetime depends on client configuration and is typically around one day.
  • Lifetimes can be automatically renewed while the user remains active.
  • Inactivity timeouts and maximum lifetimes are configurable and will be adjusted in collaboration with brokerize support.

Long-term Guest Access (RecoveryPhrase)​

Randomly generated RecoveryPhrases allow guest users to keep their data in the brokerize backend long-term without revealing their identity. Users can access their account anytime by entering their RecoveryPhrase.

Registered Users​

Registered (email-based) user accounts are supported only for certain administrative endpoints (e.g., client management or downloading order reports) and are not required for most client applications.

UserAccessTokens​

UserAccessTokens provide fine-grained permissions (e.g., for automated tasks) and differ from RecoveryPhrases, which are primarily used to sign in on new devices/browsers. Typical use cases include:

  • Automated report downloads
  • Accessing portfolio data
  • Performing other automated user actions

🚦 Rate Limits​

To protect the platform, brokerize implements rate limits:

  • Standard Limit: Currently, a limit of 100 requests per 10 seconds per client ID and user ID combination applies to all endpoints.
  • Guest User Creation: For the CreateGuestUser endpoint (which is accessible without a token), an IP-based limit of 1 request per 10 seconds applies.

Handling Rate Limits​

If your application exceeds the limit, the API responds with the HTTP status code 429 (Too Many Requests).

  • Check the Retry-After header to find out how long to wait.
  • Implement an appropriate backoff behavior in your client.

🆔 Request IDs​

The brokerize backend assigns a unique ID to each request and returns it in the x-request-id header.

  • Troubleshooting: This ID is extremely helpful when analyzing errors. We recommend logging the requestId in case of unexpected errors or displaying it to the user so that our support can track requests precisely in the backend.
  • Internal Server Errors: For errors (status 500), the ID is often part of the JSON response body.

🔐 Privileged Clients (Client Secrets)​

The brokerize API is primarily designed for direct access from browsers and apps. In some cases (e.g., pure backend-to-backend integrations), rate limits can be increased.

In these cases, a Client Secret can be used, which is sent via the x-brkrz-client-secret header. Contact our partner team if you need such a secret.

🔗 Connecting Brokers & Data Synchronization​

Users connect their brokerage accounts from either the official brokerize UI or from your app’s interface using their broker credentials.

  • Use GetBrokers to find out which brokers are available.
  • An end user can add a login via AddSession. brokerize never stores login credentials, only tokens/session IDs issued by the brokers. These are discarded as soon as the user logs out via LogoutSession.
  • Once sessions are connected, the list of portfolios, positions, and orders is synchronized into the user’s brokerize account and stored in the database. The data remains available, even if the session is disconnected, until the user actively deletes it (e.g., DeletePortfolio).
  • Data is synchronized automatically in the background; clients can optionally request a sync using TriggerSessionSync.
Session Lifecycle

🪙 Tradeable Securities​

Normally, all tradeable securities are identified by their ISIN. For instruments without an ISIN (such as crypto assets), brokerize uses special shorthand codes. Details can be found in the article Tradeable Securities.

🔄 Trade Flow​

The process of a trade can be complex as it passes through various states at the broker (e.g., TAN release, order validation). brokerize abstracts this process to a large extent. Details on the specific flow and required permissions can be found in the API reference under GetAuthInfo.

Trade Flow