“”

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.

Prepare an updated version and ask for reviews of community members in one of the mailing lists / newsgroups / forums. Post the results in the Extension Coordination Team list and we'll help you from that point.

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.