> For the complete documentation index, see [llms.txt](https://www.bluegamma.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.bluegamma.io/documentation/integrations/api/authentication.md).

# Authentication

How to authenticate with the BlueGamma API using your API key.

All BlueGamma API requests are authenticated with an API key that you issue yourself from the app.

***

### Getting an API Key

You issue your own key. There is no form and no waiting:

1. Sign in at [app.bluegamma.io](https://app.bluegamma.io)
2. Open **API Keys** in the sidebar, under Developer
3. Click **Create API key**
4. Optionally, give the key a name under **Key name (optional)**, for example Production or Excel add-in, then click **Create key**

The key is shown once, when it is created, so copy it before you leave the page. The same page has a ready-made request you can copy and run.

Trial accounts and plans that include API access can issue keys. A trial key returns live data on every index for 14 days. See [Trials and Billing](/documentation/account-and-team-management/trials-and-billing.md) for what changes when you pick a plan.

Paid organisations can hold up to 5 keys, and trial accounts 1.

***

### Using Your API Key

Include your API key in the `x-api-key` header with every request:

```bash
curl -X GET "https://api.bluegamma.io/v1/swap_rate?index=SOFR&start_date=0D&maturity_date=5Y&fixed_leg_frequency=6M" \
  -H "x-api-key: your_api_key_here"
```

***

### Example Requests

**Python:**

```python
import requests

headers = {
    "x-api-key": "your_api_key_here"
}

response = requests.get(
    "https://api.bluegamma.io/v1/swap_rate",
    params={"index": "SOFR", "start_date": "0D", "maturity_date": "5Y", "fixed_leg_frequency": "6M"},
    headers=headers
)

print(response.json())
```

**JavaScript:**

```javascript
const response = await fetch(
  "https://api.bluegamma.io/v1/swap_rate?index=SOFR&start_date=0D&maturity_date=5Y&fixed_leg_frequency=6M",
  {
    headers: {
      "x-api-key": "your_api_key_here"
    }
  }
);

const data = await response.json();
console.log(data);
```

***

### Error Responses

Errors come back as JSON with a message saying what went wrong: a `detail` field from BlueGamma, or a `message` field for API key and rate limit errors.

| Status Code         | Meaning                                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`               | The request is valid but can't be served, for example an unknown or discontinued index. The `detail` field says what to change                             |
| `403`               | Missing or invalid API key, an expired trial key, or a request your key is not allowed to make — read the `detail` field, which says which                 |
| `404`               | The requested data could not be found                                                                                                                      |
| `422`               | A parameter failed validation, for example an invalid date such as `2026-02-30`. The `detail` field says which parameter and what it expects               |
| `429`               | Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. See [Rate Limits](/documentation/integrations/api/rate-limits.md) |
| `500`, `502`, `504` | The request failed on our side, or took longer than 29 seconds (`504`). Retry later, and split very large requests                                         |

***

### Security Best Practices

* **Keep your API key secret** — Don't commit it to version control or expose it in client-side code
* **Use environment variables** — Store your key in environment variables rather than hardcoding
* **Rotate if compromised**: if a key is exposed, open the key's menu on the **API Keys** page, choose **Delete Key**, and create a new one

```bash
# Store in environment variable
export BLUEGAMMA_API_KEY="your_api_key_here"
```

```python
import os

api_key = os.environ.get("BLUEGAMMA_API_KEY")
```

***

### Need Help?

If you're having trouble authenticating, email <support@bluegamma.io>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.bluegamma.io/documentation/integrations/api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.