Core Code
Core Code Modern Dev Handbook

Basic Authentication

Still useful in controlled environments; do it safely.
On this page

What Basic Auth is

Basic Authentication sends a username and password (or token) in the Authorization header as Base64. It is simple and widely supported, but it must be used over HTTPS and it is best suited for controlled environments.

How it works

The client sends:

Authorization: Basic <base64(username:password)>

Example

GET /api/admin/stats
Authorization: Basic YWRtaW46c2VjcmV0
Accept: application/json

Where Basic Auth makes sense

  • Internal tools behind VPN
  • Service-to-service in a trusted network (still prefer stronger patterns if possible)
  • Temporary tooling, migrations, one-off admin endpoints

Where Basic Auth is a bad idea

  • Public clients (browser apps, mobile apps) where credentials can leak
  • End-user authentication at scale (use proper token flows)
  • Any context without HTTPS

Security notes

  • Base64 is not encryption. It is just encoding.
  • Always use HTTPS.
  • Rate limit and lock out abusive attempts.
  • Prefer using a generated token as the “password” rather than a real password.

Server responses

For missing/invalid credentials, return 401 and a WWW-Authenticate header.

Example: 401 response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="API"
Content-Type: application/json

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid credentials."
}

Common mistakes

  • Using Basic Auth over HTTP
  • Logging Authorization headers
  • Reusing human passwords instead of rotating tokens

Checklist

  • HTTPS only.
  • Authorization header is never logged.
  • Rate limiting exists.
Bearer Tokens →