> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication with bearer tokens

> Authenticate Straddle API requests using JWT bearer tokens. Generate API keys, manage sandbox and production credentials, and follow security best practices.

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.

<Info>
  All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
</Info>

## Obtaining Your API Key

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

1. Log in to your [Straddle Dashboard](https://dashboard.straddle.com).
2. Click the **Developer** (`</>`) icon in the top-right corner of the navigation bar.
3. Select **API Keys** from the dropdown menu.
4. Click **Generate New API Key**.
5. Copy your new API key and store it securely.

<Warning>
  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.
</Warning>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://sandbox.straddle.com/v1/accounts \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcmdfMmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6Iiwib3JnIjoiYWNtZS1jb3JwIiwiZW52Ijoic2FuZGJveCIsImlhdCI6MTcxMTU1OTAwMCwiZXhwIjoxNzExNjQ1NDAwfQ.VGhpcyBpcyBhIHNpbXVsYXRlZCBSUzI1NiBzaWduYXR1cmUgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMgb25seQ" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  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))
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## 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         |

<Warning>
  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.
</Warning>

<Tip>
  Always use sandbox API keys when developing and testing your integration. Only switch to production keys when you're ready to go live.
</Tip>

## 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 |

<Tip>
  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.
</Tip>

## Best Practices

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

1. **Keep your API key secret**: Never expose your API key in client-side code or public repositories.
2. **Use environment variables**: Store your API key in environment variables rather than hardcoding it in your application.
3. **Rotate your API keys**: Regularly generate new API keys and update your applications to use them.
4. **Monitor API key usage**: Regularly review your API key usage in the Straddle Dashboard to detect any unauthorized access.
5. **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:

```json theme={null}
{
  "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:

1. Confirm you're using the correct API key.
2. Check whether your key has been revoked or expired.
3. 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](/api-reference) for detailed information on available endpoints and how to use them.