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

# Authentication

> Authenticate your requests with a bearer token.

Every API request needs a bearer token in the `Authorization` header. Tokens are tied to your organization and inherit the limits of your subscription tier.

## Get an API key

API keys are managed from [the app](https://terrapinfinance.com/app):

1. Sign in to your Terrapin account.
2. Open the **API Keys** section.
3. Click **Generate new key** and copy the value immediately. We never display it again.

<Warning>API keys grant full access to your organization's quota. Store them in a secret manager, keep them out of source control, and rotate them if you suspect one has leaked.</Warning>

## Send the bearer token

Add `Authorization: Bearer <token>` to every request.

<CodeGroup>
  ```bash curl theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
  curl -X POST https://terrapinfinance.com/api/v1/bond_reference \
    -H "Authorization: Bearer $TERRAPIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "isins": ["US912810TM06"] }'
  ```

  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
  import os
  import requests

  resp = requests.post(
      "https://terrapinfinance.com/api/v1/bond_reference",
      headers={
          "Authorization": f"Bearer {os.environ['TERRAPIN_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={"isins": ["US912810TM06"]},
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
  const resp = await fetch("https://terrapinfinance.com/api/v1/bond_reference", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TERRAPIN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ isins: ["US912810TM06"] }),
  });
  console.log(await resp.json());
  ```
</CodeGroup>

## Responses

* `200 OK`: authenticated and processed.
* `401 Unauthorized`: header is missing, malformed, or the token has been revoked. The body is `{"errors": [{"detail": "Incorrect or no bearer token"}]}`.
* `403 Forbidden`: your tier does not include this endpoint or resource. Upgrade from [the app](https://terrapinfinance.com/app).

See [Errors](/errors) for the full status code list.

## Rotating and revoking keys

Generate a new key, switch your workload to it, then delete the old key in the app. Deleted keys stop working immediately and any in-flight calls using them will start failing with `401`.