Access Control and Capabilities

This document describes how the ADP Car Market Hub plugin uses WordPress roles and capabilities to control access to its admin features and to the custom post types it registers. It is a reference for site administrators and dealership managers who need to grant the right level of access to internal users.

When to use this document

Use this document when you need to:

• Decide which WordPress role or capability to grant to a colleague who manages vehicle listings or plugin settings.
• Audit who has access to the plugin's admin pages and to lead data.
• Integrate the plugin with a role-management plugin or a custom code snippet that maps capabilities.
• Troubleshoot "you do not have permission" errors in the plugin admin.

Overview

The plugin layers two sets of capabilities on top of the standard WordPress role system:

1. A single plugin management capability (manage_as24_imports) that gates every plugin admin page, every admin POST handler, every plugin admin AJAX action and the per-user dashboard widget.
2. A set of custom post type capabilities for the vehicle post type as24ci_car, mapped via capability_type = ['as24ci_car', 'as24ci_cars'] with map_meta_cap = true.

The plugin also creates a custom role (as24ci_editor) that holds the vehicle CPT capabilities but not the management capability. The administrator role receives both sets on plugin activation / capability upgrade.

The plugin does not modify the standard WordPress editor role.

Capabilities reference

Plugin management capability

This is the capability you grant to a user who needs to administer the plugin itself. By default it is added only to the administrator role.

Vehicle post type capabilities (as24ci_car)

The plugin registers the following custom CPT capabilities. With map_meta_cap = true, WordPress automatically resolves the singular ("meta") capabilities against per-post ownership.

These capabilities follow the standard WordPress CPT pattern. They control access to the vehicle list table and editor screens in the WordPress admin and through any code path that respects standard WordPress capability checks.

Lead post type (as24ci_lead)

The lead post type is registered as non-public. It is intentionally not exposed in the standard WordPress posts UI and is managed exclusively from the plugin's Leads admin tab. Access to that tab is gated by the manage_as24_imports capability.

For details on lead data and management, see Lead Data and Consent.

Roles created by the plugin

administrator (existing)

On plugin activation / capability upgrade:

• Receives all as24ci_car capabilities listed above.
• Additionally receives manage_as24_imports.

This means a standard administrator can manage the plugin and its content out of the box.

as24ci_editor (new role)

On plugin activation / capability upgrade, the plugin creates (or ensures) the as24ci_editor role with:

• The basic read capability.
• All as24ci_car capabilities listed above.

The role is intentionally not granted manage_as24_imports. Users in this role can manage vehicle posts (list, edit, publish, delete) but cannot:

• Open the plugin's settings, importer, tools, logs, analytics, leads, search alerts or other admin tabs.
• Use the plugin's admin AJAX or admin POST handlers.
• See the plugin's dashboard widget.

This role is intended for staff (for example a content manager) who need to maintain individual vehicle records without having access to the plugin configuration or to inquiry data.

Other WordPress roles

The plugin does not grant any of its custom capabilities to the WordPress editor, author, contributor or subscriber roles. To give those roles access, an administrator must explicitly add the relevant capabilities (using a role-management plugin or custom code).

Public REST surface

Two read-only REST routes are registered when the Enable REST API option is on:

• GET /wp-json/as24ci/v1/vehicles
• GET /wp-json/as24ci/v1/vehicles/{id}

Both routes use a permission_callback of __return_true. They are intended to expose public vehicle data only and do not require any capability. Disable the option in the plugin settings if you do not want to expose this surface.

The cron import endpoint (/wp-json/as24ci/v1/cron-import) also uses __return_true for the WordPress permission check but performs its own token-based authentication inside the callback. See Security Recommendations.

The plugin's frontend AJAX endpoints used by the contact form, favorites and search alert workflow rely on nonces and feature-specific checks (for example double opt-in tokens) instead of capability checks, because they are intended to be called by site visitors.

How to grant access

The recommended approach is to assign one of the following:

• Plugin administrator — assign the WordPress administrator role.
• Vehicle content editor — assign the as24ci_editor role.
• Custom role — using a role-management plugin or a custom snippet, add the capabilities you need from the tables above. To grant full plugin admin access without making the user a site administrator, add manage_as24_imports plus all as24ci_car capabilities to the custom role.

When using a role-management plugin, the plugin's capabilities appear under the as24ci_car post type and as a standalone capability (manage_as24_imports).

Step by step: give a colleague access to manage vehicles only

1. Open Users in the WordPress admin.
2. Edit the colleague's user account.
3. In the role selector, choose AS24 Editor (the as24ci_editor role created by the plugin).
4. Save the user.
5. Verify that the colleague can open the standard vehicle list under the AS24 Cars admin menu and edit individual vehicles, but cannot open the ADP Car Market Hub plugin admin pages.

Step by step: give a colleague full plugin access

1. Confirm that you trust the colleague with the plugin's settings, API credentials and lead data.
2. Either assign the WordPress administrator role, or add the manage_as24_imports capability and all as24ci_car capabilities to a custom role using your role-management tooling.
3. Sign in as that user and verify that the plugin admin pages are visible and that admin actions complete without permission errors.

Operational notes

• Capabilities are applied during plugin activation and on every request through a "maybe upgrade caps" routine. If a custom role is removed and recreated externally, log in as an administrator and reload the WordPress admin to give the routine a chance to re-apply the capabilities.
• The as24ci_editor role is created if it does not exist and is topped up with the CPT capabilities. Administrators can extend the role with additional WordPress capabilities (for example access to media) using a role-management plugin.
• The plugin does not currently remove the custom role or capabilities on deactivation. Verify this behavior in the current plugin version before publishing process documentation that depends on it.
• All admin POST handlers and admin AJAX endpoints check the manage_as24_imports capability and a request nonce as defence in depth, even when called from a screen that already required the capability.

Troubleshooting

• "Sorry, you are not allowed to access this page" in the plugin admin — the user does not hold manage_as24_imports. Either grant it explicitly or assign the administrator role.
• The AS24 Cars menu is missing for an editor account — confirm that the user holds at least edit_as24ci_cars. Members of as24ci_editor and administrator should always have it.
• Newly created custom role cannot edit vehicles — confirm the role holds edit_as24ci_cars and edit_published_as24ci_cars and the meta caps are mapped (map_meta_cap = true is the default for the post type).
• Lead admin tab is missing — the Leads tab is only shown to users who hold manage_as24_imports. The as24ci_editor role does not have it by design.
• Vehicle endpoints are not reachable over REST — confirm that the Enable REST API option is on; the routes are not registered when it is off.

Related documents

• Security Recommendations
• Data Storage Overview
• Lead Data and Consent
• GDPR / DSGVO Notes
• revDSG Notes