Site Key Security: Regenerate, Lockouts, and Scoped API Keys

The SEOvault AI plugin uses a site key for REST API authentication. This guide covers how to manage your site key, generate scoped API keys for granular access, handle rate limiting and lockouts, and review the audit log.

Your site key

The site key is a 40-character string generated during plugin activation. It authenticates all REST API requests from the SEOvault AI web app and any other client using the seovaultai/v1 namespace.

Where to find it

• Dashboard: go to SEOvault AI and scroll to the Site Key section. The key is masked by default. Click Show full key to reveal it.
• General Settings: go to SEOvault AI > General > Connection. The key is displayed in the connection section.
• Onboarding wizard: step 6 (Connect) displays the key with a copy button.

How it is stored

The site key is stored in the WordPress options table under seovaultseo_site_key with autoload disabled. It is not exposed in the frontend HTML or in any REST API response except the verify endpoint (which requires the key itself for authentication).

If you had the connector plugin

If the separate SEOvault AI connector plugin was previously installed, the full SEO plugin preserves the existing site key during activation. You do not need to regenerate or re-enter the key.

Regenerate the site key

If you suspect your site key has been compromised, regenerate it:

1. Go to SEOvault AI > General > Connection.
2. Scroll to the Security section.
3. Click Regenerate Site Key.
4. A confirmation dialog appears: “This will disconnect any apps using the current key. Continue?”
5. Click OK to confirm.

When you regenerate:

• A new 40-character key is generated and stored
• The old key immediately stops working
• The connection status is reset to “Waiting” (not verified)
• The connected_at timestamp is cleared
• You must update the new key in the SEOvault AI web app to reconnect

The regenerate action requires a nonce-verified POST request, so it cannot be triggered via URL or CSRF attacks.

Scoped API keys

In addition to the main site key, the plugin supports two scoped API key types. These are separate keys that grant limited access to the REST API:

Read-only API key

A read-only key can access GET endpoints only (list posts, read SEO data, check status, etc.). It cannot create, update, or delete anything.

Generate a read-only key:

1. Go to SEOvault AI > General > Security.
2. Click Generate Read-Only Key.
3. The key is displayed once. Copy it immediately – it will not be shown again.
4. Use this key in applications that only need to read data.

Write-scoped API key

A write-scoped key can access both read and write endpoints (create posts, update SEO data, publish llms.txt, etc.). It cannot access site verification or import endpoints.

Generate a write-scoped key:

1. Go to SEOvault AI > General > Security.
2. Click Generate Write Key.
3. The key is displayed once. Copy it immediately – it will not be shown again.
4. Use this key in applications that need to create or update content.

How scoping works

The plugin uses a capability-based system. Each REST API endpoint maps to a specific capability:

• site:verify – verify connection
• posts:read – list and get posts
• posts:write – create and update posts
• pages:read – list and get pages
• pages:write – update pages
• media:read – list media
• media:write – upload media
• seo:read – read SEO capabilities
• seo_import:write – run migration imports
• ai_visibility:read – read llms.txt and robots status
• ai_visibility:write – publish llms.txt, apply robots changes
• indexnow:read – read IndexNow status
• indexnow:write – submit URLs to IndexNow
• crawler_logs:read – read crawler logs
• crawler_logs:write – enable/disable crawler logging
• internal_links:read – read internal linking manifest
• sitemap:read – proxy sitemap requests
• site_health:read – read site health data
• site_health:write – clear site health logs

Key types resolve to capabilities as follows:

• Legacy (main site key) – all capabilities (read and write)
• Read-only key – only :read capabilities and site:verify
• Write key – only :write capabilities and :read capabilities

Unknown or unmapped routes default to connector:write, the most restrictive write capability.

Rate limiting

The plugin includes multi-layer rate limiting to protect against abuse:

Pre-authentication rate limiting

• Failed key attempts: 20 failed authentication attempts per IP within 15 minutes triggers a hard lockout. A warning is logged at 10 failures.
• Lockout response: HTTP 429 with Retry-After header. Error code: seovaultai_auth_lockout.
• Global per-IP throttle: 300 requests per minute per IP for all seovaultai/v1 namespace requests, including authenticated ones.

Post-authentication rate limiting

After successful authentication, requests are classified into buckets with separate limits:

• read – GET requests to read endpoints
• write – POST requests to write endpoints
• import – migration import requests
• media – media upload requests

Each bucket tracks requests per key hash with its own limit and window. Limits are intentionally generous so normal web app and admin traffic is unaffected.

Exemptions

Rate limiting is skipped for:

• HTTP OPTIONS preflight requests (CORS)
• Same-origin admin requests to the import endpoint (when an admin user with manage_options capability initiates imports from the WordPress admin)

External clients are never exempted, even on import endpoints.

Adjusting rate limits

Rate limits are filterable via the seovaultai_api_rate_limits WordPress filter. You can override the default limits array in your theme’s functions.php or a custom plugin:

add_filter( 'seovaultai_api_rate_limits', function( $limits ) {
    $limits['read'] = array( 'limit' => 200, 'window' => 60 );
    return $limits;
} );

Clear lockouts

If an IP address gets locked out due to failed authentication attempts:

1. Go to SEOvault AI > General > Security.
2. Find the API Lockouts section.
3. To clear a specific IP: enter the IP address and click Clear for this IP.
4. To clear all lockouts: click Clear all lockouts.

Clearing lockouts also resets all rate-limit counters for the affected IP(s). The action is logged in the audit log.

Audit log

The plugin maintains an audit log of API activity and admin security actions. The log is stored in a custom database table created during activation.

What is logged

• API verify requests (successful and failed)
• Write operations (post creates, updates, deletions)
• Admin actions: key regeneration, scoped key generation, lockout clearing
• Rate limit warnings and lockouts
• Import operations

View the audit log

1. Go to SEOvault AI > General > Security.
2. Scroll to the Audit Log section.
3. The log shows the most recent 50 entries with timestamp, action, IP address, and details.

Audit log retention

The audit log table grows over time. There is no automatic pruning. If the table becomes large, you can truncate it from the Tools tab or via WP-CLI.

Security best practices

• Regenerate the site key if you suspect it has been exposed
• Use scoped keys for applications that do not need full access – give read-only keys to reporting tools and write keys to content tools
• Review the audit log periodically for unexpected activity
• Clear lockouts only when you are confident the locked-out IP is legitimate
• Do not share the main site key in public repositories, chat messages, or unencrypted channels
• Use HTTPS – the web app requires a valid SSL certificate for connection

Related docs

• Connect the Plugin to the SEOvault AI Web App
• What Data Stays on Your WordPress Site (Privacy Overview)
• Getting Started with the SEOvault AI WordPress Plugin