Authenticators 

API keys 

When the api_key extension is installed (composer require maikschneider/api-key), tca_api registers an ApiKeyAuthenticator (priority 10). It accepts a key sent as X-API-Key: t3key_… or Authorization: Bearer t3key_… and maps it to a principal with source = 'api_key':

The bound user is read from the database, not logged in: keyed requests create no fe_sessions row, send no Set-Cookie and leave lastlogin untouched. The key's scopes become the principal's scopes, so a key bound to a user can never do more than its scopes allow. A key without scopes is unrestricted. Bearer tokens without the t3key_ prefix are left to other authenticators.

The bridge also adds X-API-Key to Access-Control-Allow-Headers and documents the ApiKey and ApiKeyBearer security schemes in the OpenAPI document. Without the extension none of this is registered.

Interface 

namespace MaikSchneider\TcaApi\Security\Authentication;

use Psr\Http\Message\ServerRequestInterface;

interface AuthenticatorInterface
{
    public function authenticate(ServerRequestInterface $request): AuthenticationResult;

    public function getPriority(): int;
}

An authenticator that reads a custom request header implements RequestHeaderAuthenticatorInterface instead; its getRequestHeaders() are added to Access-Control-Allow-Headers, so browser clients can send them through a CORS preflight.

Every implementation in any extension is registered automatically. The chain asks the authenticators in descending priority and stops at the first one that is applicable. SessionAuthenticator has priority -10, so credentials sent with the request are checked before a session.

authenticate() returns one of three results:

The principal 

Principal can hold a frontend user, a backend user, or both (a browser may hold both sessions). A service principal has neither: it is an authenticated caller without a TYPO3 user record.

Writes record the frontend user, otherwise the backend user, otherwise the service as actor. credential is a safe-to-log identifier of the credential the request carried (e.g. api_key:12:t3key_AbCdEfGh); the write audit log records it next to the actor. scopes lists the granted scopes, null means unrestricted. See Scopes.

Example 

use MaikSchneider\TcaApi\Security\Authentication\AuthenticationResult;
use MaikSchneider\TcaApi\Security\Authentication\AuthenticatorInterface;
use MaikSchneider\TcaApi\Security\Authentication\Principal;
use Psr\Http\Message\ServerRequestInterface;

final class PartnerTokenAuthenticator implements AuthenticatorInterface
{
    public function authenticate(ServerRequestInterface $request): AuthenticationResult
    {
        $token = $request->getHeaderLine('X-Partner-Token');
        if ($token === '') {
            return AuthenticationResult::notApplicable();
        }

        $partner = $this->partners->findByToken($token);
        if ($partner === null) {
            return AuthenticationResult::failed('X-Partner-Token realm="api"');
        }

        return AuthenticationResult::authenticated(new Principal(
            frontendUserUid: $partner->frontendUserUid,
            source: 'partner_token',
        ));
    }

    public function getPriority(): int
    {
        return 0;
    }
}

Reading the principal 

The resolved principal is the tca_api.principal request attribute. Principal::fromRequest($request) returns it, and falls back to the session for requests that did not pass the dispatcher:

$principal = Principal::fromRequest($request);
if ($principal->isBackendAdmin()) {
    // …
}

Documenting the scheme in OpenAPI 

Add the scheme your clients use in a listener for ModifyOpenApiSecuritySchemesEvent. The SecurityScheme flags tell the document which operations it applies to: each operation lists, as alternatives, every scheme that can satisfy its access role, and a credential scheme also lists the scopes the operation needs. Swagger UI then offers the scheme in its "Authorize" dialog.

use MaikSchneider\TcaApi\Event\ModifyOpenApiSecuritySchemesEvent;
use MaikSchneider\TcaApi\OpenApi\SecurityScheme;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener('my-extension/partner-token-scheme')]
final class AddPartnerTokenScheme
{
    public function __invoke(ModifyOpenApiSecuritySchemesEvent $event): void
    {
        $event->addScheme(new SecurityScheme(
            'PartnerToken',
            ['type' => 'apiKey', 'in' => 'header', 'name' => 'X-Partner-Token'],
            authenticatesFrontendUsers: true,
            isCredential: true,
        ));
    }
}

The resulting requirements:

Protected operations also document a 401 response. The Hydra API documentation has no equivalent of security schemes and is unchanged.