Frequently asked questions

Here you can find FAQ regarding the TYPO3 extension repository.
If you have a question that is not showing up here, please contact the t3o team.

Why does my extension not appear in the list of recently updated extensions?

The extension index which acts as the data source for the list on typo3.org is only updated every few minutes, so you might have to wait a little longer.

I can't find extension XY - what's wrong?

Maybe you're looking for an extension key like "tx_address"? Then leave out the "tx_" prefix - that's a syntax used in TYPO3 internally. Make sure you're searching for the right extension key!

If all that still doesn't help, please get in contact with the t3o team.

How can I delete extension keys / extensions?

If you never uploaded an extension using a certain extension key, you can delete it using the extension key tool.

For reasons of integrity, you cannot delete used extension keys nor uploaded extensions. If your extension has a security issue, please contact the Security Team.

If you don't want to maintain your extension any more, you can transfer the extension key to the user "abandoned_extensions".

The extension key I want to have is still taken. What can I do?

There are two possibilities:

  1. If the owner has not uploaded any version of the extension, you can contact him and ask for the extension key. If there is no reaction by the owner, please get in contact with the t3o team.
  2. If the owner has uploaded minimum one version (you can find out by searching for the key), all you can do is offer a contribution.

I get a 500 server error when trying to upload an extension! What's wrong?

There are two possible causes for the 500:

  1. Please check that your extension is not bigger than 30MB (if you have big libraries in the extension think about composer)
  2. Your file ext_emconf.php has a field which is a concatenated string. Our PHP parser cannot parse it in the moment, so please don't concatenate.

If you are sure no point is throwing the 500 error, please contact the t3o team.

Although I uploaded a manual, it is not displayed at docs.typo3.org - why?

  1. Check that your documentation is located at the right place in your extension. That is ./Documentation/Index.rst or ./README.rst.
  2. If your documentation still is not rendered, there can be an syntax error in your reStructuredText.
    Warnings and errors will be saved to https://docs.typo3.org/typo3cms/extensions/YOUREXTKEY/warnings.txt, so take a look there.
    In addition you can use the extension sphinx to proof if everything is fine on your local system.
  3. Rendering takes time. The documentation is fetched cyclically by docs server

To get an introduction to reStructuredText take the sphinx extension as an example. Further more the format is well documented at sphinx-doc.org/rest.html.
In addition the documentation of the sphinx extension has further information.

I have problems with the reST format to document my extension - where can I get help?

On the page https://docs.typo3.org/Extensions/ you get a list of tools and workflows how to best document your extension in reST.

How downloads of extensions are counted?

TER counts extension downloads:

  • via TYPO3 Extension Manager (non-composer mode)
  • via Download button (TER pages)
  • via Packagist

As we switched to the new download counter on November 30th 2020, there are some remarks on the download numbers:

  • Packagist downloads are fetched first on November 2020. All downloads before November are not counted.
  • The number above the chart is the old counter (without packagist) until November 30th 2020.

I'd like to stop maintaining an extension.

Transfer the extension to the user "abandoned_extensions". This way it's clear that there is no active maintainer anymore. If someone wants to take over the Extension Coordination Team can immediately transfer the key to the new maintainer.

An extension is owned by "abandoned_extensions". I don't want to maintain it, but I have some improvements.

First, take a look if the extension has a repository to work on. If you have some improvements, you can create a patch there.
But often if an extension is abandoned there is no community work anymore. Either you take the key and do the maintenance or improve it for your own project only.

Why was my upload rejected?

The ZIP file contains neither a composer.json nor an ext_emconf.php.
TER needs one of the two at the top level of the archive to know what it is looking at. Add a composer.json with "type": "typo3-cms-extension".

The composer.json or ext_emconf.php sits in a subdirectory.
You packed the extension directory itself. Pack its contents instead, so composer.json is the first level inside the archive. On the command line: cd my_ext && zip -r ../my_ext_1.2.3.zip .

The composer.json could not be read.
The file is not valid JSON, or it is not a JSON object. Run composer validate locally; it points at the line.

The composer.json does not describe a TYPO3 extension.
Its "type" must be "typo3-cms-extension". Libraries and projects are not accepted, and the TYPO3 Core would not detect them either.

The configured version does not match.
Your composer.json (or your ext_emconf.php, if composer.json declares no version) says a different version than the archive name. Either remove the version field from composer.json, which is the usual choice for tagged packages, or update it before you pack.

No dependency for TYPO3 Core given.
require in your composer.json has no typo3/cms-core entry, and no ext_emconf.php declares a TYPO3 constraint. TER needs to know which TYPO3 versions your extension supports.

Invalid version constraint for TYPO3 Core given.
The TYPO3 versions you support must overlap with a maintained TYPO3 version, ELTS included. Extensions that only support end-of-life versions are not accepted.

.

Latest updates in 2026

We made some improvements to TER in 2026, also regarding extensions, find all questions about this here.

Do I still need an ext_emconf.php?

No. composer.json is the manifest. Keep an ext_emconf.php only if your extension still supports TYPO3 v13 or older in classic mode, because those versions look for the file, or if you want to set a category and a state, which composer.json cannot express. TYPO3 v14 and v15 do not read the file at all.

Where does the title of my extension come from?

From the description in composer.json, split at the first " - ". "description": "News - Versatile news system" gives the title "News" and the description "Versatile news system". Without a separator the whole description is the title. If you also ship an ext_emconf.php with a title, that title is used when composer.json has no separator. The TYPO3 Core reads it the same way since v14.

Which version does TER use?

The one in the archive name, my_ext_1.2.3.zip, and in the publish command when you use tailor or the REST API. If your composer.json declares version or extra.typo3/cms.version, it must match. Most extensions do not declare a version in composer.json, and that is fine.

How are my Composer constraints shown as TYPO3 versions?

TER translates them. "typo3/cms-core": "^13.4" becomes the range 13.4.0 to 13.99.99, "^12.4 || ^13.4" becomes 12.4.0 to 13.99.99. php is kept as a PHP dependency. typo3/cms-* packages become the system extension key. Other packages are matched against the composer names registered on TER; a package TER does not know is left out, because the Extension Manager could not install it anyway.

What happens to category and state?

composer.json has no field for them. If you ship an ext_emconf.php, its category and state are used. Otherwise the category stays empty and the state is "stable". Both are only shown on extensions.typo3.org and in the Extension Manager list; nothing depends on them.

Is the ZIP I download the file the author uploaded?

For versions that require TYPO3 14.3 or newer: yes, byte for byte, and the published SHA-256 is the hash of that file. For versions that also support older TYPO3 versions, TER builds the ZIP from the extension files and adds a generated ext_emconf.php, because TYPO3 v13 in classic mode needs one. The SHA-256 then belongs to that built file.

What about the .t3x download?

The t3x is the archive format the Extension Manager used up to TYPO3 14.2. It is still generated for every version, so older installations keep working. The Extension Manager of TYPO3 14.3 and newer installs the ZIP and verifies its SHA-256. The t3x will be phased out for versions that require TYPO3 14.3 or newer.

How do I publish from my CI?

Use tailor. composer require --dev typo3/tailor, create a token with ter:token:create, then ./vendor/bin/tailor ter:publish 1.2.3 --comment "Release notes". tailor packs the extension, validates the manifest the way TER reads it, and uploads. See the tailor README for GitHub Actions and GitLab pipeline examples.

REST API

Here you can find FAQ regarding the REST API.

Which scopes or permissions do I need?

First of all: All endpoints (expect the public endpoints /ping and /docs) require authentication.

Further we distinguish between the authentication method (e.g. Basic Auth or Bearer Auth) and the scopes (permissions). The methods only specify how you can authenticate against the REST API. The scopes (permissions) specify which endpoint can be accessed. Therefore the OpenAPI specification defines both, the available authentication methods (also known as "security schemas") and the necessary scopes. Due to some OpenAPI specification limitations, it's currently only possible to visualize the scopes for the Bearer Auth method. They however also apply to Basic Auth.

The following table displays the available methods and necessary scopes for each endpoint.

Endpoint Authentication methods  Scopes
GET /ping - -
GET /docs - -
POST /auth/token Basic Auth -
POST /auth/token/refresh  Basic Auth -
POST /auth/token/revoke  Basic Auth -
GET /extension Basic Auth, Bearer Auth  extension:read 
GET /extension/{key} Basic Auth, Bearer Auth extension:read
POST /extension/{key} Basic Auth, Bearer Auth extension:write
PUT /extension/{key} Basic Auth, Bearer Auth extension:read + extension:write 
DELETE /extension/{key} Basic Auth, Bearer Auth extension:read + extension:write
GET /extension/{key}/versions Basic Auth, Bearer Auth extension:read
POST /extension/{key}/transfer/{username}  Basic Auth, Bearer Auth extension:read + extension:write
GET /extension/{key}/{version} Basic Auth, Bearer Auth extension:read
POST /extension/{key}/{version} Basic Auth, Bearer Auth extension:read + extension:write
DELETE /extension/{key}/{version} Basic Auth, Bearer Auth extension:admin
POST /extension/{key}/version/{review_state}  Basic Auth, Bearer Auth extension:review

More information regarding the specific endpoints can be found in the interactive OpenAPI specification.

Further information:

  • Using access tokens, all required scopes must be defined separat. Having extension:write does NOT include extension:read.
  • If you authenticate with Basic Auth, the extension:read and extension:write scopes are automatically applied for this request.
  • The scopes are bound to the fe_users user groups. That means, the scopes extension:admin and extension:review are only available if the user which authenticated with Basic Auth has this user groups assigned. The scopes extension:read and extension:write are available for all activated TYPO3.org users.

How should I use this REST API?

To support you as much as possible, we’ve built a new CLI tool called tailor.  This tool already includes the most common endpoints.  You can e.g. use it in your extensions by including it via composer as a dev-dependency. It's also possibility to directly integrate it into your continuous integration process. A detailed documentation and the whole source code is available on GitHub.

Which extensions can I access?

Despite the authentication method used, when you have the extension:read scope assigned, you can access all extensions from TER, like it's also possible via the web interface.  This is also possible if you use a restricted access token. Technically speaking, all GET endpoints can be accessed without further scope checks. If you however want to change an extension, e.g. upload a new extension version or update the extensions meta data, you must be the owner of that extension. The only exception is  the POST /extension/{key} endpoint, which allows to register a new extension key. This could however also be restricted, if you use an access token, which is restricted to a subset of extensions.

In any case, if you are not allowed to access an extension key you will recieve the "The user is not allowed to access this extension." error (Code: 1602754874).

How can I create an access token

Acces tokens can be created using the Create token section or through the the POST /auth/token endpoint.

Available options for token creation:

  • Name: Specifiy a name for the access token (e.g. the extension key the token is restricted to)
  • Expires: Specifiy the date on which the access token expires, if not refreshed
  • Scopes: Specifiy the scopes for the token
  • Extensions: Specify a subset of your extensions, the token should be restricted to

For the detailed endpoint specification refer to the interactive OpenAPI specification.

Note: You have to authenticate with Basic Auth for this endpoint. Therefore, it's not possible to create an access token using another access token for authentication.

How can I refresh an access token

Acces tokens can be refreshed using the Refresh token section or through the the POST /auth/token/refresh endpoint by providing the corresponing refresh token.

Note: You have to authenticate with Basic Auth for this endpoint. Therefore, it's not possible to refresh an access token using the same or another access token for authentication.

How can I revoke an access token

Acces tokens can be revoked using the Revoke token section or through the the POST /auth/token/revoke endpoint by providing the access token to revoke.

Note: You have to authenticate with Basic Auth for this endpoint. Therefore, it's not possible to revoke an access token using the same or another access token for authentication.

How can I restrict an access token to a subset of extensions?

Per default, you can manage all your extensions with one personal access token. However it sounds reasonable to restrict access tokens to a subset of extension keys. This can be easily done either on the Create token section or directly using the REST API endpoint /auth/token by providing the extension keys to be accessible as query parameter: ?extensions=some_key,another_key.

Note: An access token which is restricted to a subset of extensions can NOT be used to create new extension keys.

I created an access token, how can I now use it to access the API?

According to RFC 6750 there are three different possibilities to use the access token for Bearer Auth:

  1. Authorization Request Header Field

      GET /api/v1/<endpoint> HTTP/2
      Host: extensions.typo3.org
      Authorization: Bearer <your_token>
     
  2. Form-Encoded Body Parameter

    POST /api/v1/<endpoint> HTTP/2
    Host: extensions.typo3.org
    Content-Type: application/x-www-form-urlencoded
    access_token=<your_token>
     
  3. URI Query Parameter

    GET /api/v1/<endpoint>?access_token=<your_token> HTTP/2

Can I use multiple authorization header in one request?

According to RFC 7230 there is the possibility to specify multiple authorization fields as comma-separated list. This means a request can contain both, Bearer Auth and Basic Auth. Please note that the different fields are only evaluated until one is successful.

How can I integrate the REST API into my CI?

For this purpose we have created the tailor cli tool. You can easily integrate it into your existing CI. There are already some examples how such integration could look like for GitHub workflows and GitLab pipelines.

What does "The user lacks necessary permissions for this endpoint." mean?

You will encounter this error if the authentication has failed. This is the most common error and can have many reasons. Some of them are:

  • The provided credentials are wrong (e.g. username or password)
  • You tried to authenticate with an expired or revoked token
  • The provided token does not fulfil the requirements (e.g. necessary scopes)
  • The provided token could not be verified / validated

How can I delete an extension which has uploaded versions

You can delete an extension using the DELETE /extension/{key} endpoint. If the extension has already uploaded versions, it won't be deleted but abandoned.

How can I see my created tokens?

There is currently no endpoint implemented which allows to access your created tokens. Therefore, it's important that you store your created tokens immediately after creation at a save place. There is no way to receive a token a second time, since we do not store the generated tokens.

Why do the rate limiting headers not change?

The REST API will feature a rate limiting in the future. This is currently not implemented but already documented in the OpenAPI specification to be able to introduce this to version 1 at any time later. Therefore, the responses do already include the documented rate limit headers (x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset) even if their value is currently just static. If you intend to create a custom client for the REST API, you are already able to implement necessary checks based on these headers. The corresponding HTTP response code will be 429 and is also already documented in the OpenAPI specification.