---
title: Authenticate with Basic Auth
slug: authenticate-with-basic-auth
type: how-to
plugin: huxx-connect
summary: Configure Basic Auth with a username and password so every request sends a base64-encoded Authorization header.
keywords: [basic auth, username, password, authorization header, 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]
---

Basic Auth sends a username and password pair, encoded with
[base64](/docs/connect/explanation/glossary/#base64), in the `Authorization`
header of every request. Many APIs use it with an API key as the username
and a fixed or empty password — check your provider's docs for what goes in
each slot.

> **Quick version:**
> 1. Go to **HuxxConnect → APIs** and click **Configure** on your API.
> 2. In **API Configuration**, set **Auth Type** to **Basic Auth**.
> 3. Fill in **Username** and **Password**.
> 4. Click **Save API**.
>
> Every request now sends `Authorization: Basic <base64 of username:password>`.

## Configure the API

:::novice
Base64 is an *encoding*, not encryption — anyone who
sees the header can decode it back to the username and password. Basic
Auth is only safe when the API URL uses `https://`. 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
   **Basic Auth**.
3. Fill in **Username** and **Password**. If your provider says to use an
   API key as the username with no password, don't paste the key into
   **Username** directly — see the storage note in the next step.
4. Click **Save API**. The **Password** is stored encrypted; the
   **Username** is not — it is stored in plaintext and kept in
   [configuration exports](/docs/connect/how-to/import-and-export-configurations/)
   even when credentials are stripped. For the key-as-username pattern,
   put the key in `wp-config.php` or an environment variable and enter the
   ALL_CAPS constant name or `env:VAR_NAME` reference in **Username**
   instead — both fields resolve references — see
   [Store credentials outside the database](/docs/connect/how-to/store-credentials-outside-the-database/).

<!-- screenshot-todo: api-detail--auth-basic--username-password | alt: Basic Auth fields with a username filled in and the password value masked -->

## What gets sent

HuxxConnect joins the two values as `username:password`, base64-encodes the
result, and sends it in the `Authorization` header. With **Username**
`demo_user` and **Password** `hxc_example_token_123`
(`// Replace with your real token.`):

```
GET /v2/reports HTTP/1.1
Host: api.example.com
Authorization: Basic ZGVtb191c2VyOmh4Y19leGFtcGxlX3Rva2VuXzEyMw==
```

Decoding `ZGVtb191c2VyOmh4Y19leGFtcGxlX3Rva2VuXzEyMw==` gives back
`demo_user:hxc_example_token_123` — which is why HTTPS is non-negotiable.

Source: `src/Auth/Providers/BasicAuth.php` — the header is
`'Basic ' . base64_encode( username . ':' . password )`.

## Verify it works

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

## Advanced

- **Per-endpoint override** — expand an endpoint's **Authentication
  Override** accordion to give one endpoint different credentials or a
  different auth type.
- **Colons in usernames** — the wire format separates username and password
  with a colon, so a username containing `:` is ambiguous to the server.
  Passwords may contain colons; usernames should not (per the HTTP spec).

## If it didn't work

- **Response is `401` or `403`.** Confirm the pair against the provider's
  cURL example (`curl -u username:password ...`), and check which slot the
  provider expects an API key in — key-as-username with an empty password
  is common. Inspect the outgoing request with
  [Debug API requests](/docs/connect/how-to/debug-api-requests/).
- **The Password field shows "Credentials could not be decrypted due to
  encryption key mismatch. Please re-enter your credentials."** The
  encryption key changed since the password was saved — common after moving
  or cloning a site. Re-enter it and click **Save API**; see
  [Choose an encryption tier](/docs/connect/how-to/choose-an-encryption-tier/).
- **It works in the browser but not from HuxxConnect.** A browser session
  may be logged in with cookies; the API itself still requires the header.
  Re-test with cURL using `-u` to confirm the credentials work outside a
  browser before debugging the HuxxConnect config.