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

# Authenticate Avalex API Requests with HTTP Basic Auth

> Use HTTP Basic Auth as a fallback authentication method for Avalex. Encode your username and password in Base64 and pass them in the Authorization header.

HTTP Basic Auth is a fallback authentication method supported by Avalex. It is most useful for quick manual testing with curl, where you want to make an authenticated request without first obtaining a JWT token. For any production integration, [JWT authentication](/auth/jwt) is strongly recommended instead.

## How Basic Auth Works

You Base64-encode the string `username:password` and pass the result in the `Authorization` header on every request:

```
Authorization: Basic <base64(username:password)>
```

## Making a Request with Basic Auth

The easiest way to use Basic Auth is to let curl handle the encoding for you with the `-u` flag:

```bash theme={null}
curl http://localhost:8080/customers \
  -u ada:a-strong-password
```

### Constructing the Header Manually

If you need to build the header yourself — for example, in a script or HTTP client that does not handle Basic Auth natively — you can Base64-encode your credentials and include them directly:

```bash theme={null}
# Base64 encode credentials
echo -n "ada:a-strong-password" | base64
# Output: YWRhOmEtc3Ryb25nLXBhc3N3b3Jk

# Use in header
curl http://localhost:8080/customers \
  -H "Authorization: Basic YWRhOmEtc3Ryb25nLXBhc3N3b3Jk"
```

## Staff Account Requirements

For a staff account to authenticate successfully, it must have `active: true` set in its configuration. Requests from inactive accounts are rejected regardless of whether the credentials are correct.

<Note>
  Unlike JWT, Basic Auth requires credentials to be verified server-side on **every request**, which adds overhead. For production applications with frequent API calls, use JWT tokens instead.
</Note>

<Warning>
  Always use HTTPS when sending Basic Auth credentials. Over plaintext HTTP, your Base64-encoded password is trivially decoded by anyone who can observe the request in transit.
</Warning>