Security 

Default access roles 

Operations not listed in security fall back to sensible defaults:

Access roles 

Configuration 

use MaikSchneider\TcaApi\Enum\AccessRole;

'security' => [
    // list and show are PUBLIC by default — only specify to restrict them
    'create' => AccessRole::FE_USER,
    'update' => AccessRole::OWNER,      // Only the record owner may update
    'delete' => AccessRole::OWNER,
],

Callable voters 

For custom access logic, use a callable instead of an AccessRole enum value. The callable receives the PSR-7 server request and an optional record array (for object-level security):

'security' => [
    'create' => [MyAccessChecker::class, 'checkCreatePermission'],
],

The callable must return true to grant access or false to deny it. The caller is available as Principal::fromRequest($request), see Authenticators.

class MyAccessChecker
{
    public static function checkCreatePermission(
        \Psr\Http\Message\ServerRequestInterface $request,
        ?array $record = null
    ): bool {
        // Custom access logic
        return true;
    }
}

Scopes 

Credentials can carry scopes that limit what they may do. A scope names a resource and an access level:

Scopes always restrict. A credential with scopes may only perform the operations they cover, even when its role would allow more, so a key bound to a frontend user is never more powerful than its scopes. This also applies to PUBLIC operations and to nested creates into another resource. Sessions and credentials without scopes are unrestricted.

A role can additionally require scopes:

'security' => [
    'show'   => AccessRole::API_KEY,                       // any credential
    'create' => [AccessRole::API_KEY, ['articles:write']], // a credential with the scope
    'update' => AccessRole::FE_USER,                       // session or user-bound credential
],

Invalid scope strings fail when the configuration is loaded. Which scopes a credential carries is decided by the extension that authenticates it, see Authenticators.

Ownership 

The ownership section enables declarative record-level security for write operations. It pairs with AccessRole::OWNER in the security config.

use MaikSchneider\TcaApi\Enum\AccessRole;

'security' => [
    'create' => AccessRole::FE_USER,
    'update' => AccessRole::OWNER,
    'delete' => AccessRole::OWNER,
],
'ownership' => [
    'column' => 'fe_user_id',   // DB column holding the owner's FE user UID
],

What this does:

• On create — the fe_user_id column is automatically set to the authenticated FE user's UID server-side. The client cannot supply this value; it is stripped from the request body regardless of the column's groups config.
• On update/delete — the record's fe_user_id is compared to the current FE user's UID. If they don't match the request returns 403.

'ownership' => [
    'column'      => 'fe_user_id',      // column checked on update/delete (also written on create)
    'setOnCreate' => 'fe_creator_id',   // additional column written on create only
],

'ownership' => [
    'column'        => 'fe_user_id',
    'beAdminBypass' => false,           // default: true
],

Table write restrictions 

The API enforces a built-in deny list for tables that must never be written through the API regardless of security configuration. Attempting to write to any of these tables returns 403 Forbidden:

• be_users, be_groups, be_sessions
• fe_sessions
• sys_filemounts, sys_be_shortcuts, sys_action, sys_log

This protection is unconditional — no resource configuration can unblock these tables. The policy can be tightened further (an allow list, or additional denied tables) and every write is audit-logged; see Write privilege model.

Denied access 

When access is denied, the API returns:

• 401 Unauthorized — when the request carries credentials that are invalid, e.g. a wrong, expired or revoked API key.
• 403 Forbidden — when the caller is anonymous or does not have sufficient privileges.

See How tca_api sees identity.