Smart API-key rotation

How Aimogen Pro tracks the health of individual API keys, honours Retry-After, quarantines bad credentials and recovers automatically, without ever storing raw keys in health records.

Every provider key field in Aimogen Pro accepts multiple keys, one per line. Smart API-key rotation, added in 2.8.7, tracks each key health independently so a failing key is taken out of service without taking the provider with it.

Enable it#

Aimogen Pro › Settings › Advanced AI Settings

What it does#

Tracks failures per key. Each key gets a health record. A failure on one key does not affect the others.

Skips unhealthy keys. Keys in cooldown or quarantine are removed from the selection pool until they recover.

Honours Retry-After. When a provider sends a Retry-After header or an equivalent hint in the error body, that value is used instead of your configured cooldown, if it is longer.

Escalates credential problems. Authentication and quota errors are treated as more serious than a transient rate limit and produce a longer hold.

Recovers automatically. A key returns to the pool when its hold expires, or immediately after a successful request.

Failure handling by category#

retry_failure is the conservative case: an inner retry path did not expose the provider error, so the plugin holds the key briefly rather than assuming a credential problem. All holds are clamped to a maximum of 24 hours.

Once a key is quarantined, a subsequent lesser failure does not downgrade it — the quarantine stands until it expires.

Raw keys are never stored in health records#

This is worth stating plainly because it is a real design decision in the code.

Health records are keyed by an HMAC-SHA256 fingerprint of the key, salted with the WordPress auth salt. The record stores the provider, the failure category, the status, a failure count and the cooldown expiry — never the key itself.

The consequences:

• Diagnostics are safe to share. The health summary shown in System Info and in support diagnostics cannot leak a credential.
• Fingerprints are site-specific. Because they are salted with your auth salt, the same key on two sites produces different fingerprints, and a fingerprint cannot be reversed to a key.
• Rotating WordPress salts resets key health. Existing records become unmatchable and every key starts healthy again. Harmless, and occasionally a useful reset.

Health state lives in transients, so it survives page loads but not a full cache flush.

Interaction with the provider circuit breaker#

Key rotation deliberately changes when the circuit breaker trips.

If a rate limit is hit but the provider still has at least one healthy key, the plugin does not cool down the model or trip the breaker. It rotates to the healthy key and continues. Only when no healthy key remains does the failure escalate to the provider.

This is the behaviour you want: with five OpenAI keys, one hitting its limit should not stop the other four.

Multiple keys per post#

Settings › API Keys › Use Multiple API Keys When Creating The Same Post decides whether all requests for one post share a key, or each request picks fresh.

Key rotation works either way. With the setting off, a key that fails mid-post is still replaced.

Monitoring#

System & Logs › System Info reports the key health summary: how many keys per provider are healthy, in cooldown or quarantined, with the reason and the expiry. No key material appears.

To reset health manually — after fixing billing, for example — use the reset control on that screen rather than waiting for the quarantine to expire.

The aimogen_smart_key_state_changed action fires whenever a key changes state:

add_action( 'aimogen_smart_key_state_changed', function ( $fingerprint, $state ) {
    if ( $state['status'] === 'quarantined' ) {
        wp_mail(
            get_option( 'admin_email' ),
            'Aimogen: an API key was quarantined',
            sprintf(
                'Provider: %s, reason: %s, until: %s',
                $state['provider'],
                $state['category'],
                gmdate( 'Y-m-d H:i', $state['cooldown_until'] )
            )
        );
    }
}, 10, 2 );

The fingerprint passed to the hook is the HMAC, not the key.

When to use multiple keys#

Worth it when

• You run bulk generation and hit rate limits
• You want a run to survive one key being revoked or running out of credit
• You separate spend across projects or clients with different keys

Not worth it when

• Your volume is low. One key is simpler
• The keys share a single account quota. Five keys on one exhausted account are five exhausted keys

Common problems#

A key stays quarantined after I fixed billing Quarantine runs for the configured hours. Reset key health from System Info.

Rotation seems not to happen Check that Reliability Mode is on. Rotation is inactive without it.

All keys quarantined at once They share an account whose quota is exhausted, or they were all revoked. Check the provider dashboard.

Related#

• Reliability Mode
• AI provider configuration
• Where credentials are stored