> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/getting-started/api-keys.md).

# API Keys

One set of API keys for the Haystack Router and the Haystack API.

The [Haystack Router](/haystack-dev/haystack-router/api-order-router.md) and the [Haystack API](/haystack-dev/haystack-api/overview.md) take the same kind of API key. Each key is granted access to the router, the Haystack API, or both. The Haystack API refuses a key without access to it with `401`. The router answers one with `400 invalid api key`, as it does an unknown key.

Send the key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: hay_sk_..." "https://api.hay.app/api/assets/trending"
```

A key in the URL ends up in server logs, browser history and caches, so always prefer the header. Each API's page lists the exceptions it still accepts: the router's [`apiKey` parameter](/haystack-dev/haystack-router/api-order-router.md#api-keys-and-rate-limits), and the Haystack API's [WebSocket](/haystack-dev/haystack-api/overview.md#authentication).

## Key kinds

The prefix tells you what kind of key it is:

| Prefix    | Kind        | Use it from                                                                                                                                                         | Rate limits             |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `hay_sk_` | Secret      | Your own servers only. Never ship a secret key in a web page or an app.                                                                                             | Per key                 |
| `hay_pk_` | Publishable | Web pages, mobile and desktop apps. A browser key works only from the origins registered for it. A native key, for apps that send no `Origin`, works from anywhere. | Per end-user IP address |

A publishable key is public by design: anyone can read it from your page or app. Browsers can use a browser key only from your origins (outside a browser, `Origin` is just a claim), and each user is limited to their own share of the rate limit, so a copied key buys nobody more than they would get on their own. Keep anything that needs a higher limit on your servers, with a secret key.

## Getting a key

Two public free-tier keys let you start without asking, each for one API:

| API             | Key                                 | Limits, per IP address                                                                                                 |
| --------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Haystack Router | `hay_pk_4zhj33wahuxfplteyif5xpcgnm` | 60 requests per minute. See the [Swap API](/haystack-dev/haystack-router/api-order-router.md#api-keys-and-rate-limits) |
| Haystack API    | `hay_pk_s5ltqlgh6i44npsb2m2qarpolc` | Half of each endpoint's [base limit](/haystack-dev/haystack-api/overview.md#rate-limits), and 1,000 requests a day     |

Both are native publishable keys: they work from servers, scripts and apps, and anyone may use them, so each IP address gets its own share. Browsers can't use the Haystack API key from your own site (it isn't answered with CORS), so a web page needs a browser key registered for its origins.

For a key of your own, with higher limits, your origins, or Haystack API access, email <support@txnlab.dev>. We set each key up from what you tell us, so include all of the following. A request without it comes back with questions before any key is issued.

1. **Who you are:** your project or company name, its website or app store link, and a contact we can reach about changes to your key or incidents: a name, an email address, and a Discord or Telegram handle.
2. **What you're building:** a few sentences on your product and what it does with Haystack. For example, a wallet that lets its users swap, a portfolio tracker that shows prices, or a trading bot.
3. **Which API you need:** the Haystack Router, the Haystack API, or both. For the Haystack API, list the endpoints you'll call (or the pages of these docs they're on), and say whether you'll use the [WebSocket](/haystack-dev/haystack-api/websocket.md).
4. **Where your calls come from.** This decides the [key kind](#key-kinds), and you can ask for one of each:
   * **Your servers:** a secret key.
   * **Web pages:** a publishable browser key. List every origin it runs on, with its scheme and any port, staging included: `https://app.example.com`, `https://staging.example.com`.
   * **Mobile or desktop apps:** a publishable native key.
5. **Expected traffic** for each API: your typical and peak requests per minute, and your requests per day. For a publishable key, give these per user, since its limits apply to each user's IP address, along with your number of daily active users. For the router, say how many swaps a day you expect to execute as well as how many quotes.
6. **For the router only:**
   * A short name for your app. The router writes it in your swaps' transaction notes, so they're credited to you.
   * Whether you already handle [First Stage taxed tokens](/haystack-dev/haystack-router/special-tokens.md#first-stage-taxed-tokens) with First Stage's own middleware. If you do, we leave the router's wrapping of those swaps off for your key.

{% hint style="warning" %}
Don't ask for router limits to show prices. A router quote is slow and is meant for a swap a user is about to make. Prices, price lists and live price updates come from the [Haystack API](/haystack-dev/haystack-api/assets.md#prices), which answers far faster. See [Prices: use the Haystack API](/haystack-dev/haystack-router/api-order-router.md#prices-use-the-haystack-api).
{% endhint %}

Keep a secret key out of source control and client code. If one leaks, email us to have it replaced.
