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
Copied!

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
Copied!

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
Copied!

Managing keys on the command line 

Create a key 

vendor/bin/typo3 apikey:create --title="CI deploy"
Copied!
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
Copied!

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
Copied!

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

Managing keys in the backend 

Administrators create and edit keys in the regular record form, like any other record on the root page (Content > Records, page 0). The key is generated when the record is saved. The form then shows it once, with a button that copies it to the clipboard. Only its hash is stored, so reloading the form or opening it again does not show it any more.

Bound to selects whether the key is a service key or bound to a frontend or backend user, and shows only the matching user field. Switching it clears the binding of the other user type when the record is saved.

The same rules apply as for apikey:create. A record that breaks one, for example an invalid IP range or a key bound to a frontend and a backend user at once, is not saved, and the error is shown above the form.

On TYPO3 v14 the module Administration > Integrations > API Keys lists all keys with their identifier, identity, scopes, expiry, last use and status. Create API key and the edit button open the record form. The revoke button hides the record, like apikey:revoke. A key that was saved with Save and close is shown once at the top of the module instead.

Until the key is shown, it is kept in the backend user session, encrypted with a key derived from the session id. The session table only stores a hash of that id, so the database alone does not reveal it.

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}
Copied!

gitleaks rule:

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