The Contao Manager is distributed as a Phar application. Appart from the graphical user interface, the application also provides a REST API to interact with the webserver and Contao application.
The Contao Manager API is available under
/api wherever you installed the Phar.
If your website runs on
https://example.com, and the Contao Manager has been uploaded as
contao-manager.phar.php to the root folder, the API will be available at
To learn more about the available REST features, please consult our OpenAPI documentation.
Authentication is necessary to interact with any API endpoint of the Contao Manager. There are two ways to authenticate, depending on your use case.
This is the preferred approach if your UI is accessing the Contao Manager through the browser, similar to what the Contao Manager does itself. Your UI will not need to store any authentication details, as the browser securely takes care of that. However, these access details also automatically expire, so they are only useful for interactions where the user needs to log in to the Contao Manager prior to any API access.
Consult the OpenAPI Docs on how to use the
For long term authentication or without involving the browser, the Contao Manager supports authentication tokens. Tokens are always bound to a specific user acccount and work similar to any other OAuth authentication.
The Contao Manager does not actually implement standard OAuth, because it cannot. OAuth requires you to register an application ID prior to accessing the OAuth endpoint. As an example: on Facebook, you have to register as a developer and register your application to get a private key, before you can access the API and get a token. Because the Contao Manager is distributed to every user, we cannot have a (predefined) list of applications that would be allowed to use OAuth.
Creating a token is only possible after authenticating to the Contao Manager. Technically,
this means a user has to authentication through the
/api/session endpoint in a browser,
to then be able to create an access token. Because users should not enter their username
and password on your website (where you could grab the password), the Contao Manager provides
a built-in workflow to get an API token.
Given the URL examples above, all you have to do is point the browser to the following location:
The supported & required parameters are:
scope is the requested access. Currently only
admin is a supported value, as the Contao Manager does not yet
client_id is a representative name for your application, which will be presented to the user.
client_id is also stored alongside the token, each
client_id will get a different access
token, but the same
client_id will get the same token again on a subsequent request.
return_url is where the user is sent back to after allowing or denying access to your application.
The user will be presented with the following dialog with two options:
When clicking on Allow Access, the Contao Manager will generate a token, append a
query parameter to the
return_url argument, and redirect the user to that URL.
You can then read the token from the query parameters and store it on your application.
If the user clicks on Deny Access, they will be redirected to the
return_url, but without a
Now that you sucessfully aquired a token, you can use it to perform API requests on the Contao Manager. For each request, the token must be sent in an HTTP header.
Using tokens for authentication has been standardized as RFC 6750 and is commonly known as Bearer Authentication,
which is fully supported by the Contao Manager. Add the
Authentication: Bearer <your-token> to your request header to authentication API requests.
Unfortunately, there are known issues with some versions of the Apache webservers, which will remove
Authentication: Bearer headers
from your request, so they will never reach the Contao Manager. To circumvent this issue, the Contao Manager supports an alternative
Contao-Manager-Auth: <your-token> header for authentication.
If you are in control of the webserver where Contao Manager is running, and you can make sure you don’t run into the mentioned issue, using
Authentication header is the preferred way. If you need to support any Contao Manager on any unknown host, the best
approach is to use the
Contao-Manager-Auth header which will be ignored by Apache.