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}`,
  },
});

What the Token Protects

With global routes enabled, every page is served as JSON through a single catch-all route. That route matches every HTTP method and validates the bearer token before it resolves anything:

return [
    'headless' => [
        'globalRoutes' => true,
        'token' => 'your-secret-token'
    ]
];

• Page JSON requires the token.
• Clean file URLs such as /about/hero.jpg require the token. They are additionally opt-in through Kirby's content.fileRedirects option, which is disabled by default – without it, files are only reachable through their media URL.
• Media URLs such as /media/pages/about/hero.jpg never require the token. Kirby serves them from its own routes, which is why images returned by $file->url() keep working in a browser that cannot send an Authorization header.
• The /api/__sitemap__ and /api/__template__ endpoints require the token as well. They are not part of the catch-all and stay available even with globalRoutes disabled – which also means they are public whenever no token is set.

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
    ]
];