---
title: Authenticate with an API Key
slug: authenticate-with-an-api-key
type: how-to
plugin: huxx-connect
summary: Configure API Key authentication with your provider's exact key name, sent as a request header or a query string parameter.
keywords: [api key, header, query string, authentication, credentials]
version_added: 1.2.5
version_updated: 1.2.5
level: intermediate
related: [understanding-authentication, authenticate-with-a-bearer-token, store-credentials-outside-the-database, authentication-types, debug-api-requests]
---

API Key auth sends a single secret under a name and in a location your
provider chooses — a custom header or a query string parameter. Unlike
[Bearer Token](/docs/connect/how-to/authenticate-with-a-bearer-token/),
there is no standard, so copy both the name and the location from your
provider's docs.

> **Quick version:**
> 1. Go to **HuxxConnect → APIs** and click **Configure** on your API.
> 2. In **API Configuration**, set **Auth Type** to **API Key**.
> 3. Set **Location** to **Header** or **Query String** to match your
>    provider's docs.
> 4. Enter the provider's exact key name in **Header Name** (or
>    **Parameter Name**), and the key itself in **API Key**.
> 5. Click **Save API**.

## Configure the API

:::novice
An API key is a secret string from your provider's
dashboard that identifies your account on every request. The provider's
"Authentication" docs page tells you what to name it and where to put it.
Background: [Understanding API authentication](/docs/connect/explanation/understanding-authentication/).
:::

1. Go to **HuxxConnect → APIs** and click **Configure** on the API.
2. In the **API Configuration** section, set **Auth Type** to **API Key**.
   Three fields appear.
3. **Location** — choose **Header** or **Query String**. Use whichever your
   provider documents; if it accepts both, prefer **Header** (query strings
   end up in server logs and cached URLs).
4. **Header Name** / **Parameter Name** — the label follows your Location
   choice. Enter the provider's exact name, e.g. `X-API-Key` for a header
   or `api_key` for a query parameter. Always fill this in: the `X-API-Key`
   default applies only when the field has never been set — clearing a
   previously saved name sends an empty name, not the default.
5. **API Key** — paste the key itself.
6. Click **Save API**. The key is stored encrypted; to keep it out of the
   database entirely, use a constant or `env:` reference instead — see
   [Store credentials outside the database](/docs/connect/how-to/store-credentials-outside-the-database/).

<!-- screenshot-todo: api-detail--auth-api-key--location-header | alt: API Key auth fields showing Location set to Header, Header Name X-API-Key, and a masked API Key value -->

## What gets sent

With **Location: Header**, **Header Name** `X-API-Key`, and the key
`hxc_example_token_123` (`// Replace with your real token.`):

```
GET /v2/reports HTTP/1.1
Host: api.example.com
X-API-Key: hxc_example_token_123
```

With **Location: Query String** and **Parameter Name** `api_key`, the same
key travels in the URL instead:

```
GET /v2/reports?api_key=hxc_example_token_123 HTTP/1.1
Host: api.example.com
```

Source: `src/Auth/Providers/ApiKeyAuth.php` — the key is added under your
chosen name to either the headers or the query parameters.

## Verify it works

Expand an endpoint and click **Run Test**. A `200` response confirms the
key is accepted.

## Advanced

- **Per-endpoint override** — expand an endpoint's **Authentication
  Override** accordion to give that one endpoint different credentials or a
  different auth type.
- **Query-string keys and caching** — the query location adds the key to
  the request URL, so it appears anywhere URLs are logged. If your provider
  supports a header, switch **Location** to **Header**.

## If it didn't work

- **Response is `401` or `403`.** Two usual causes: the **Location** doesn't
  match the provider docs (a key sent as a header when the API expects a
  query parameter, or vice versa), or the name is wrong — providers are
  strict about the exact header or parameter name. Compare the outgoing
  request against the provider's cURL example using
  [Debug API requests](/docs/connect/how-to/debug-api-requests/).
- **The API Key field shows "Credentials could not be decrypted due to
  encryption key mismatch. Please re-enter your credentials."** The
  encryption key changed since the key was saved — common after moving or
  cloning a site. Re-enter the key and click **Save API**; see
  [Choose an encryption tier](/docs/connect/how-to/choose-an-encryption-tier/).
- **The key works in cURL but not here.** Check for stray whitespace pasted
  around the key, and confirm you didn't include the name in the value
  field (the **API Key** field takes only the secret itself).