Authentication

Bearer Token Authentication

Protect the Kirby Headless /api/kql endpoint with a bearer token by setting kql.auth to 'bearer' and defining a secret token in your config.php. This provides a modern alternative to basic authentication for KQL requests:

return [
    'kql' => [
        // Enable bearer token authentication for KQL
        'auth' => 'bearer'
    ],
    'headless' => [
        'token' => 'your-secret-token'
    ]
];

Include the token in your requests using the Authorization header:

const response = await fetch("https://example.com/api/kql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KIRBY_API_TOKEN}`,
  },
});

Basic Authentication

By default – unless kql.auth is set to 'bearer' – the /api/kql endpoint uses Kirby's native API authentication (Panel session, or HTTP Basic auth when api.basicAuth is enabled), while keeping caching and multi-language support:

return [
    // Enable HTTP Basic authentication for the Kirby API
    'api' => [
        'basicAuth' => true
    ],
    // Use Kirby's native API authentication for KQL (default)
    'kql' => [
        'auth' => true
    ]
];