API authentication with bearer tokens

Securing your API requests is crucial when integrating with Straddle. This guide will walk you through the authentication process, ensuring your API calls are properly authenticated and your data remains secure.

Overview

Straddle uses Bearer Token authentication via JSON Web Tokens (JWT) for all API requests. Each request must include a valid API key in the Authorization header as a Bearer token.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Obtaining Your API Key

Before you can authenticate your requests, you’ll need to obtain an API key from the Straddle Dashboard:

Log in to your Straddle Dashboard.
Click the Developer (</>) icon in the top-right corner of the navigation bar.
Select API Keys from the dropdown menu.
Click Generate New API Key.
Copy your new API key and store it securely.

Your API key carries many privileges, so be sure to keep it secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, or in your application logs.

Using Your API Key

To authenticate an API request, include your API key in the Authorization header. The value should be formatted as Bearer YOUR_API_KEY. Here’s an example of how to include the Authorization header in your API requests:

curl https://sandbox.straddle.com/v1/accounts \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcmdfMmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6Iiwib3JnIjoiYWNtZS1jb3JwIiwiZW52Ijoic2FuZGJveCIsImlhdCI6MTcxMTU1OTAwMCwiZXhwIjoxNzExNjQ1NDAwfQ.VGhpcyBpcyBhIHNpbXVsYXRlZCBSUzI1NiBzaWduYXR1cmUgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMgb25seQ" \
  -H "Content-Type: application/json"

const apiKey = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcmdfMmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6Iiwib3JnIjoiYWNtZS1jb3JwIiwiZW52Ijoic2FuZGJveCIsImlhdCI6MTcxMTU1OTAwMCwiZXhwIjoxNzExNjQ1NDAwfQ.VGhpcyBpcyBhIHNpbXVsYXRlZCBSUzI1NiBzaWduYXR1cmUgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMgb25seQ'

async function listAccounts() {
  const res = await fetch('https://sandbox.straddle.com/v1/accounts', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  })
  const json = await res.json()
  console.log(json)
}
listAccounts().catch(err => console.error('Error:', err))

import requests

api_key = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcmdfMmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6Iiwib3JnIjoiYWNtZS1jb3JwIiwiZW52Ijoic2FuZGJveCIsImlhdCI6MTcxMTU1OTAwMCwiZXhwIjoxNzExNjQ1NDAwfQ.VGhpcyBpcyBhIHNpbXVsYXRlZCBSUzI1NiBzaWduYXR1cmUgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMgb25seQ'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get('https://sandbox.straddle.com/v1/accounts', headers=headers)

print(response.json())

API Environments

Straddle provides two public environments, each with its own base URL and API keys:

Environment	Base URL	Purpose
Sandbox	`https://sandbox.straddle.com`	Testing and development — no real financial transactions are processed
Production	`https://production.straddle.com`	Live transactions with real customer data and banking networks

API keys are environment-specific. A sandbox API key will not authenticate against the production environment, and vice versa. Always verify you are using the correct key for your target environment.

Always use sandbox API keys when developing and testing your integration. Only switch to production keys when you’re ready to go live.

Required Headers

In addition to the Authorization header, Straddle recommends including the following headers with your requests:

Header	Required	Description
`Content-Type`	Yes	Set to `application/json` for request bodies
`Request-Id`	No	A unique identifier useful for tracking and debugging individual API requests
`Correlation-Id`	No	Used to group related requests within larger operations or transactions for easier debugging

While Request-Id and Correlation-Id are optional, we strongly recommend including them — they make it much easier to trace and debug API requests when troubleshooting issues.

Best Practices

To ensure the security of your integration, follow these best practices:

Keep your API key secret: Never expose your API key in client-side code or public repositories.
Use environment variables: Store your API key in environment variables rather than hardcoding it in your application.
Rotate your API keys: Regularly generate new API keys and update your applications to use them.
Monitor API key usage: Regularly review your API key usage in the Straddle Dashboard to detect any unauthorized access.
Match keys to environments: Always confirm your API key matches the environment you’re targeting before processing requests.

Handling Authentication Errors

If your API key is invalid, expired, or has been revoked, you’ll receive a 401 Unauthorized response:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "type": "authentication_error"
  }
}

If you encounter this error, verify the following:

Confirm you’re using the correct API key.
Check whether your key has been revoked or expired.
Ensure you’re targeting the correct environment (sandbox or production) for the key you’re using.

Next Steps

Now that you understand how to authenticate your API requests, you’re ready to start integrating with Straddle. Check out our API Reference for detailed information on available endpoints and how to use them.

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

API authentication with bearer tokens

Overview

Obtaining Your API Key

Using Your API Key

API Environments

Required Headers

Best Practices

Handling Authentication Errors

Next Steps

​Overview

​Obtaining Your API Key

​Using Your API Key

​API Environments

​Required Headers

​Best Practices

​Handling Authentication Errors

​Next Steps

Overview

Obtaining Your API Key

Using Your API Key

API Environments

Required Headers

Best Practices

Handling Authentication Errors

Next Steps