For Platforms building on Embed, you have the ability to make API calls on behalf of your embedded accounts. This guide will walk you through the process of adding the necessary information to your API calls to act on behalf of your connected accounts.

​
Overview

You can make API calls for your embedded accounts in two ways:

  1. Server-side using the Straddle-Account-Id header and the embedded account ID, per request
  2. Client-side by passing the embedded account ID as an argument to the client library

To ensure optimal performance and reliability, Straddle has established rate limits and allocations for API endpoints. These limits apply collectively to all requests made on behalf of embedded accounts.

​
Server-Side Requests: Using the Straddle-Account-Id Header

For server-side API calls, you can make requests as embedded accounts using the special header Straddle-Account-Id with the Straddle account identifier (prefixed with acct_) of your platform user.

​
Example: Creating a Charge

Here’s an example that shows how to create a Charge with your platform’s API secret key and your user’s Account identifier:

curl https://sandbox.straddle.io/v1/charges \
  -H "Authorization: Bearer 51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1" \
  -H "Straddle-Account-Id: 1234567890" \
  -d amount=1000 \
  -d currency=usd \
  -d paykey="pk_test_TYooMQauvdEDq54NiTphI7jx"

​
Client-Side Requests

For client-side API calls, you can pass the embedded account ID as an argument when initializing the Straddle client. Here’s an example:

COMING SOON

Be cautious when using client-side requests for embedded accounts. Ensure that you’re not exposing sensitive information or granting unnecessary permissions to the client.

​
Best Practices

When making API requests for embedded accounts, keep these best practices in mind:

  1. Use server-side requests when possible: This gives you more control over the API calls and keeps sensitive information secure.
  2. Validate the embedded account ID: Before making a request on behalf of an embedded account, ensure that the account ID is valid and belongs to your platform.
  3. Handle errors gracefully: Be prepared to handle errors that may occur when making requests for embedded accounts, such as account not found or insufficient permissions.
  4. Monitor API usage: Keep track of the API calls made on behalf of your embedded accounts to ensure you’re within rate limits and to detect any unusual activity.
  5. Use webhooks: Set up webhooks to receive real-time notifications about events related to your embedded accounts.

​
Rate Limits

Straddle applies rate limits to API requests to ensure fair usage and system stability. These limits apply collectively to all requests made by your platform, including those made on behalf of embedded accounts.

If you need higher rate limits for your platform, please contact Straddle support to discuss your requirements.

​
Conclusion

Making API requests on behalf of embedded accounts is a powerful feature that allows you to build sophisticated platforms on top of Straddle. By following the guidelines in this document, you can ensure that you’re making these requests correctly and securely.

For more information on specific API endpoints and how they behave when used with embedded accounts, refer to our API Reference documentation.