Usage

Key format

A key consists of the prefix t3key_ and 32 random bytes in unpadded base64url, 49 characters in total:

t3key_KhhNfTRL-5tLoriJVo5I-BQRJWiLD3GqlvEcPDPeHmg

The prefix plus the next eight characters (t3key_KhhNfTRL) form the identifier. It is stored in plain text, shown in the backend and in logs, and identifies a key without revealing it. The full key is only shown once, when it is created. The database stores an HMAC hash of it.

Sending a key

Send the key in one of two headers:

curl -H 'X-API-Key: t3key_KhhNfTRL-5tLoriJVo5I-BQRJWiLD3GqlvEcPDPeHmg' \
    https://example.com/api/articles

curl -H 'Authorization: Bearer t3key_KhhNfTRL-5tLoriJVo5I-BQRJWiLD3GqlvEcPDPeHmg' \
    https://example.com/api/articles

Prefer X-API-Key behind Apache, see Apache and the Authorization header. Never put a key in the query string; such requests are always rejected.

In CI pipelines and scripts read the key from a secret variable instead of writing it into the script:

curl --fail -H "X-API-Key: ${TYPO3_API_KEY}" https://example.com/api/articles

Managing keys on the command line

Create a key

vendor/bin/typo3 apikey:create --title="CI deploy"

Name	Type
--title	string
--fe-user	int
--be-user	int
--created-by	int
--scope	string, repeatable
--expires	string
--allowed-ip	string, repeatable
--site	string, repeatable

--title

Type: string
Required: true

A label that tells you what the key is used for.

--fe-user

Type: int

Binds the key to a frontend user. Without --fe-user and --be-user the key is a service key.

--be-user

Type: int

Binds the key to a backend user. A key is bound to one user at most. A bound user that is deleted, disabled or outside its start and end time makes the key invalid.

--created-by

Type: int

Records a backend user as creator of the key, e.g. the person who requested it. The creator is shown in the backend and by apikey:list, and does not affect authentication.

--scope

Type: string, repeatable

Restricts the key to a scope. The extension does not interpret scopes; the API that consumes the key defines them, e.g. articles:read. Commas separate several scopes in one value. A key without scopes is unrestricted, but a given --scope without a value (--scope=",") is rejected. The same applies to --allowed-ip and --site.

--expires

Type: string

A date (2027-01-01) or a relative time (+90 days) after which the key stops working.

--allowed-ip

Type: string, repeatable

Restricts the key to an IP address or a CIDR range, e.g. 10.0.0.0/8 or 2001:db8::/32.

--site

Type: string, repeatable

Restricts the key to the site with this identifier.

The command prints the key once. Store it in your secret manager right away; it cannot be recovered.

List keys

vendor/bin/typo3 apikey:list

Shows identifier, title, bound user, scopes, expiry, last use and status of every key. Secrets are never shown.

Revoke a key

vendor/bin/typo3 apikey:revoke t3key_KhhNfTRL
vendor/bin/typo3 apikey:revoke 12

Takes the identifier or the uid. Revoking hides the record, so it stays available for auditing.

Secret scanning

The fixed prefix lets secret scanners find keys that end up in a repository.

GitHub custom pattern:

t3key_[A-Za-z0-9_-]{43}

gitleaks rule:

[[rules]]
id = "typo3-api-key"
description = "TYPO3 API key (maikschneider/api-key)"
regex = '''t3key_[A-Za-z0-9_-]{43}'''
keywords = ["t3key_"]