Site banner Colonel's Pensieve

The /.well-known/ Directory

📅 👤 colosieve

What Is It?

The /.well-known/ directory is a standardized location on HTTP servers for hosting site metadata. Defined by RFC 8615, it’s the “public reception desk” where bots and services ask standard questions about your site.

Common Uses

SSL/TLS Certificates (/.well-known/acme-challenge/)

  • Let’s Encrypt uses this to verify domain ownership
  • Server places a random file here to prove control

App Links

  • /.well-known/apple-app-site-association - iOS deep linking
  • /.well-known/assetlinks.json - Android app verification

Security (/.well-known/security.txt)

  • Contact info for reporting vulnerabilities
  • Used by bug bounty programs

Authentication (/.well-known/openid-configuration)

  • OAuth/OIDC discovery endpoint
  • Auto-configures login URLs and public keys

Password Management (/.well-known/change-password)

  • Browser integration for password resets
  • Redirects to your actual password change page

Example: opencode CLI

The opencode CLI uses /.well-known/opencode for custom authentication:

opencode auth login https://ai.example.com

The CLI fetches https://ai.example.com/.well-known/opencode:

{
  "auth": {
    "command": ["gcloud", "auth", "print-identity-token"],
    "env": "OPENCODE_TOKEN"
  },
  "config": {
    "api": "https://ai.example.com/v1"
  }
}

This tells the CLI to run gcloud auth print-identity-token, store the output in OPENCODE_TOKEN, and use the custom API endpoint.

Why It Exists

Prevents cluttering the root directory with config files while ensuring automated tools can always find them at predictable paths.

← Back to home