Drupal Integration

SitePulse connects to Drupal via JSON:API (Drupal 8.7+) or the Drupal REST API (Drupal 8.x). JSON:API is preferred — it is enabled by default in Drupal 9+ and provides a consistent field structure. The Metatag module is recommended for SEO field access.

Prerequisites

• Drupal 8.7 or later
• JSON:API module enabled (core in Drupal 9+, drupal/jsonapi in Drupal 8)
• A Drupal user account with Content Editor role or custom role with node edit permissions
• Basic Auth or OAuth2 authentication (see below)
• HTTPS on your Drupal site

Recommended modules

Authentication options

SitePulse supports two authentication methods for Drupal:

Basic Authentication

The simplest option. Enable the basic_auth module and use your Drupal username and password directly in SitePulse. Requires HTTPS — credentials are sent as a Base64-encoded header.

1. Enable basic_auth module: drush en basic_auth
2. In SitePulse: Project → Settings → Integrations → Connect Drupal
3. Enter your Drupal site URL, username, and password.

OAuth2 (recommended for production)

Use the Simple OAuth module to create a client credentials grant. This avoids storing user passwords in SitePulse.

1. Install: composer require drupal/simple_oauth && drush en simple_oauth
2. Generate keys: drush simple-oauth:generate-keys ../private
3. Create an OAuth2 client with the client_credentials grant type.
4. In SitePulse: enter the Client ID and Client Secret.

Connect Drupal in SitePulse

1. Go to your project → Settings → Integrations.
2. Click Connect Drupal.
3. Enter:
   • Drupal URL — your site root (e.g. https://example.com)
   • Auth method — Basic Auth or OAuth2
   • Credentials for your chosen method
4. Click Test Connection — SitePulse will call GET /jsonapi to verify.
5. Click Save.

What SitePulse can patch

Without the Metatag module, SitePulse falls back to patching attributes.title (the node title) for title changes only. Meta description patches require Metatag.

Metatag module field mapping

When Metatag is installed, SitePulse detects it by checking for the metatag resource in the JSON:API schema. Patches are sent as:

{
  "data": {
    "type": "node--article",
    "id": "{uuid}",
    "attributes": {
      "metatag": [
        { "tag": "meta", "attributes": { "name": "title", "content": "New Title" } },
        { "tag": "meta", "attributes": { "name": "description", "content": "New description." } }
      ]
    }
  }
}

Image alt text

Drupal stores image alt text on the media entity or as an inline field on the entity referencing the image. SitePulse patches field_image[alt] (the most common field name) via JSON:API. If your content type uses a different image field name, configure it in Project Settings → Integrations → Drupal → Advanced.

Required permissions

The authenticated user must have:

• edit any <content-type> content — to patch node fields
• edit any file — to patch image alt text
• access content — to read entity data

Troubleshooting

"401 Unauthorized" with Basic Auth Confirm basic_auth module is enabled. Some hosting providers (Pantheon, Acquia) require HTTPS for Basic Auth to work.

"403 Forbidden" on patch The user account does not have edit permissions for the content type. Assign the Content Editor role or grant edit any <type> content permission.

"404 Not Found" on JSON:API endpoint Verify the JSON:API module is enabled: drush pm:list | grep jsonapi. The JSON:API base path is /jsonapi by default.

Metatag not detected Ensure Metatag is both installed AND the metatag values are enabled for the content type being audited. Go to Admin → Configuration → Search and metadata → Metatag to verify.