Deprecation of the Akeeba Backup JSON API v2

26 August 2026

Akeeba Backup 10.4.0 was released today, August 26th, 2026. As stated in the release notes, this version deprecates the Akeeba Backup JSON API v2, and authenticating to the Akeeba Backup JSON API v3 using the Secret Word. We recommend all third party implementations to move to using the Akeeba Backup JSON API v3, using a Joomla API token for authentication. These two deprecated features will be removed in Akeeba Backup 11.0, scheduled for release in October 2027.

The problems with API v1 and v2

The Akeeba Backup JSON API v1 and v2 used an endpoint in the frontend of your site. This is susceptible to breakage due to various factors such as:

  • third-party plugins not being aware the Joomla frontend application can server content other than HTML.
  • redirections issued by a localization solution, including Joomla's built-in multi-language feature.
  • CDNs and caching proxies ignoring the no-cache HTTP headers sent with our API responses.

The end result is that a minority of users have been complaining to us about being unable to take remote backups when the root cause is well and truly outside our control.

Moreover, both Akeeba Backup JSON API v1 and v2 authenticate using a single "Secret Word" which does not have access scoping. If you have this Secret Word you can take backup, delete them locally and remotely, reconfigure the backup profile, create a new backup profile etc. This creates an obvious security issue: if it falls into the wrong hands, an attacker can easily subvert your Akeeba Backup installation to exfiltrate your entire site.

Why is v3 different

Akeeba Backup JSON API v3 is materially different because it's implemented as a Joomla webservices plugin. This means that it exposes functionality through Joomla's API application. This was only possible to implement in Akeeba Backup 9 which ran on Joomla 4.0 and later versions due to the fact that Joomla only introduced its API application with Joomla 4.0, released in August 2021.

For backwards compatibility reasons we decided that the original v3 implementation would use two possible authentication methods:

  1. Our Secret Word. Still unscoped, and giving full access to the component. The idea is that if you were using an integration which already had your site's Secret Word you could still use it for a transition period before moving to Joomla API Token authentication.
  2. Joomla's API Token. These tokens are user-scoped. They authenticate and authorize a specific user. You can only take actions against the component that this specific user can.

In Joomla 4 the two authentication methods were practically equivalent. Joomla appeared to only allow Super User accounts to create API tokens – and that's how it was communicated at the time. This meant that the access to the component you were given with a Super User token was always unlimited, just like using the Secret Word.

However, that was never the case, even though it's never been communicated properly. You can configure your site to allow non-Super User account to create Joomla API tokens. This is a major win for security. The Joomla API application only allows actions against the component that the owning user of the API Token is authorized for. This means that you can create a lesser-privileged user with just the API Login and Akeeba Backup -> Backup privileges to take backups but, crucially, unable to delete backups, manage backup profiles, and reconfigure the backup profile.

This is the reason we are finally moving away from using Secret Word authentication with unlimited access and into proper authorization using Joomla privileges.

What changed in Akeeba Backup 10.4.0

Akeeba Backup 9.0.0 through 10.3.6 assumed that only a Super User account could log into the Joomla API application. They completely lacked authorization checks. If you were authenticated, you had full access to Akeeba Backup.

With Akeeba Backup 10.4.0 we have two separate paths:

  • If you were authenticated with a Joomla API Token we will be performing Joomla authorization checks for every JSON API v3 action you are taking.
  • If you were NOT authenticated with a Joomla API Token but DID provide a valid Secret Word you are given full access to the component. This is the part that's being deprecated.
  • If you failed both authentication checks you do not get access to Akeeba Backup at all.

How to create a less-privileged, backup-only user

First, we need to create a special group called API Access. This will allow us to give Joomla API application access to non-Super-User accounts. This must be carried out be a Super User.

  1. Log into your site as a Super User.
  2. Go to Users Groups and create a new user group with the name API Access. Make sure the Group Parent is set to Public.
  3. Go to System, Setup, Global Configuration.
  4. Click the Permissions tab.
  5. Click on the API Access user group.
  6. Set the following permissions:
    • Web Services Login: Allowed.

Now, we need to tell Joomla it is allowed to mint API tokens for our API Access user group. Again, this must be carried out by a Super User.

  1. Log into your site as a Super User.
  2. Go to System, Manage, Plugins.
  3. Search for the "User - Joomla API Token" plugin.
  4. Click on the plugin
  5. In the "Allowed User Groups" section add our "API Access" user group.
  6. Click on Save & Close.

Next up, create a Joomla! User Group which grants backup-only privileges:

  1. Log into your site as a Super User.
  2. Go to Users Groups and create a new user group with the name Backup Only. Make sure the Group Parent is set to Public.
  3. Go to System, Setup, Global Configuration.
  4. Click on Akeeba Backup for Joomla™ on the left hand sidebar/
  5. Click the Permissions tab.
  6. Click on the Backup Only user group.
  7. Set the following permissions:
    • Backup: Allowed.

Create a new user account. Choose the following user groups and only the following user groups:

  • API Access
  • Backup Only
  • Manager

Log out of your site's administrator and log back in with your new user.

Edit your user account (User Menu at the top, then Edit Account).

Click on the Joomla API Token tab. Set Active to Yes, then click on Save & Close.

Copy the Token and keep it safe.

Log out of your site's administrator and log back into it as a Super User.

Edit the user you created above and remove them from the Manager group.

You now have a user which cannot log into the site's frontend and backend. It can only log into the Joomla API application; this is granted by the API Access user group. The user has no privileges to do anything other than taking backups; this is granted by the Backup Only user group. You can now use this user's token in the service or application you use to take backups, e.g. Akeeba Remote CLI, Akeeba Panopticon, mySites, Watchful, etc.

This is much safer. If the token gets stolen the attacker can no longer subvert Akeeba Backup to exfiltrate your entire site by taking a backup and transferring to an (S)FTP server under their control, or by surreptitiously modifying your backup profile.