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

# Authentication — API keys & the Authorization header

> Authenticate Vulcx API requests with an API key using the Authorization: Bearer header. How to get a key, use it from the SDK, widget, and WebSocket, and keep it secure.

Every request to the Vulcx API (`https://api.vulcx.xyz`) is authenticated with an API key,
**except** `GET /health` and `GET /api/v1/tokens`, which are public and require no key. Keys look
like `vulcx_` followed by a long hex string, and you send them in the standard `Authorization:
Bearer` header (or as a `?key=` query parameter — the only option for the WebSocket stream).

<Note>
  This applies to the WebSocket stream too: `GET /api/v1/stream` requires a key just like every
  other endpoint. See [WebSocket streaming](#websocket-streaming) below for the query-param form.
</Note>

<Note>
  Vulcx is **free during beta** — there are no paid tiers yet. You still need a key so we can
  apply [rate limits](/api-reference/rate-limits) and keep the service healthy.
</Note>

## Get an API key

<Steps>
  <Step title="Request a key">
    During beta, keys are issued through our Telegram. Reach out and ask —
    keys are granted at no cost.

    <Card title="Get an API key on Telegram" icon="telegram" href="https://t.me/vulcxsupport" horizontal>
      Message the Vulcx team on Telegram and request a key.
    </Card>
  </Step>

  <Step title="Store it as an environment variable">
    Never hard-code a key in source. Keep it in an environment variable:

    ```bash theme={"theme":"github-dark"}
    export VULCX_KEY="vulcx_your_key_here"
    ```
  </Step>
</Steps>

## Authenticate a request

Send your key in the `Authorization` header on every request:

<CodeGroup>
  ```bash cURL theme={"theme":"github-dark"}
  curl "https://api.vulcx.xyz/api/v1/quote?inputMint=So11111111111111111111111111111111111111112&outputMint=uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG&amount=1000000000&swapMode=ExactIn" \
    -H "Authorization: Bearer $VULCX_KEY"
  ```

  ```typescript TypeScript theme={"theme":"github-dark"}
  const res = await fetch(
    "https://api.vulcx.xyz/api/v1/quote?inputMint=So11...&outputMint=uSd2...&amount=1000000000&swapMode=ExactIn",
    { headers: { Authorization: `Bearer ${process.env.VULCX_KEY}` } },
  );
  ```

  ```python Python theme={"theme":"github-dark"}
  import os, requests

  res = requests.get(
      "https://api.vulcx.xyz/api/v1/quote",
      params={
          "inputMint": "So11111111111111111111111111111111111111112",
          "outputMint": "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",
          "amount": "1000000000",
          "swapMode": "ExactIn",
      },
      headers={"Authorization": f"Bearer {os.environ['VULCX_KEY']}"},
  )
  ```
</CodeGroup>

## SDK and widget

The [SDK](/sdk/configuration) and [widget](/widget/attributes) take the key directly — you don't
set headers yourself.

<CodeGroup>
  ```typescript SDK theme={"theme":"github-dark"}
  import { VulcxSDK } from "@vulcx/sdk";

  const sdk = new VulcxSDK({ apiKey: process.env.VULCX_KEY });
  ```

  ```html Widget theme={"theme":"github-dark"}
  <vulcx-swap api-key="vulcx_your_key_here" theme="dark"></vulcx-swap>
  ```
</CodeGroup>

## WebSocket streaming

Browsers can't set custom headers on a WebSocket connection, so the streaming endpoint accepts the
key as a `key` query parameter instead:

```text theme={"theme":"github-dark"}
wss://api.vulcx.xyz/api/v1/stream?key=vulcx_your_key_here
```

## Keep your key secret

<Warning>
  A key grants access under your account's rate limits. Treat it like a password.
</Warning>

* **Server-side keys stay on the server.** Don't commit keys to git or ship them in a public repo.
* **Browser and widget usage exposes the key** in client code. For client-side embeds, use a key
  you've provisioned for that purpose and rotate it if it leaks.
* **Rotate compromised keys** by requesting a new one and retiring the old.

## Errors

A missing or invalid key returns an authentication error:

| Status             | Meaning                                   |
| ------------------ | ----------------------------------------- |
| `401 Unauthorized` | No API key was provided.                  |
| `403 Forbidden`    | The key is invalid, disabled, or revoked. |

The SDK surfaces these as `AuthError` — see [SDK error handling](/sdk/error-handling). For
throughput limits and the `429` response, see [Rate limits](/api-reference/rate-limits).


## Related topics

- [Stream Quotes](/api-reference/stream/index.md)
- [Handling Errors](/guides/handling-errors.md)
- [Vulcx API reference — quote, swap & instructions](/api-reference/introduction.md)
- [Introduction to Vulcx — best-price swaps on Fogo](/get-started/introduction.md)