Authentication

Permissions

Kirby's REST API is based on user permissions. This helps increase security by blocking operations for unauthorized users. You can read more about specific user permissions in the Users permissions docs ›

Session-based Authentication

The Panel uses session-based authentication, which is not really typical for REST APIs, but works best in combination with frontend authentication and is also the most secure way when you don't have control over the backend environment and you cannot work with trusted private keys.

We use sessions purely for authentication to keep communication with the API stateless.

Session-based authentication requires CSRF token validation. The CSRF token has to be sent in the X-CSRF header for every request. A token can be generated with the csrf() helper in the backend.

Sessions also require a correct session cookie for every request. Therefore, session-based authentication works best when you make API calls from the frontend of the same site/domain.

Example

Here is a small JavaScript example using the fetch API. This setup assumes that it is running on the same server as the API and that you have access to our csrf() helper (e.g. in a template).

This is ideal if you want to build a single page application on top of Kirby or if you need to fetch parts of your site dynamically via JavaScript. It could be combined with a React or Vue based application.

<html>
  <head>
    <title>API Example</title>
  </head>

  <body>
    <script>
      const csrf = "<?= csrf() ?>";

      fetch("/api/pages/example", {
          method: "GET",
          headers: {
            "X-CSRF" : csrf
          }
        })
        .then(response => response.json())
        .then(response => {
          const page = response.data;
          // do something with the page data
        })
        .catch(error => {
          // something went wrong
        });
    </script>
  </body>
</html>

HTTP Basic Auth

To enable truly stateless, remote authentication, our API offers HTTP Basic auth as an alternative to sessions. This is particularly useful if you want to make requests from the backend of a different site or in a command line tool.

Basic auth has to be activated in the config:

/site/config/config.php

return [
    'api' => [
        'basicAuth' => true
    ]
];

When Basic auth is activated, you must send an Authorization header with every request.

Basic auth is only available over HTTPS to avoid that the credentials are sent over the wire unencrypted with every request. This restriction can be disabled via the allowInsecure option.

Example

Here's a simple example of a remote request in PHP with our Remote class.

<?php

$response = Remote::get('https://yoursite.com/api/pages/example', [
  'headers' => [
    'Authorization: Basic ' . base64_encode($email . ':' . $password)
  ]
]);

$page = json_decode($response->content())->data;