Laravel APP_KEY Rotation Playbooks for Real-World Scenarios

Rotating your Laravel APP_KEY is easy to describe in theory—but in practice, the timing and method depend on why you’re rotating. A routine hygiene rotation looks very different from an emergency breach response.

Planned or Safe Rotation

Most teams should schedule regular rotations as a matter of hygiene—typically once a year. This cadence balances risk reduction (you don’t leave one key in place forever) with operational overhead (rotating more often than necessary just creates noise). Annual rotation is a good baseline unless you have stricter compliance needs.

If you haven’t seen it yet, Part 1 explains the basics of rotating your Laravel APP_KEY, including:

• Manual “big bang” rotation and its side effects
• How to set up a "key ring" and why
• Code examples for the KeyRingEncrypter and Service Provider binding
• A background re-encrypt job for database columns

This rotation is invisible to users: sessions, cookies, and encrypted data continue working until they naturally migrate.

Breach or Compromise (Hard Rotation)

via GIPHY

If you know or strongly suspect the APP_KEY has been exposed, you must assume it’s compromised and act immediately. Leaving a compromised key in place means an attacker could still decrypt existing data, forge cookies, or validate fake signed URLs. In this situation, the old key cannot remain in use at all — and if you’re running with a key ring, it must be removed from the ring right away.

Steps:

1. Deploy with a brand-new APP_KEY and do not include the old compromised key in your key ring (if your using one).
2. Force logout by changing the session cookie name and flushing the store.

// bump (or add) suffix
'cookie' => env(
    'SESSION_COOKIE',
    Str::slug(env('APP_NAME', 'laravel'), '_').'_session_v2'
),

3. Accept that all previously signed URLs will fail.
4. For encrypted DB fields: you have two options

Option A (safest): This approach wipes out encrypted values that can’t be trusted anymore and marks those records as needing re-verification. Instead of trying to salvage data with the compromised key, you require users—or another safe source of truth, like an upstream API—to provide fresh values.

In practice, this usually means flagging affected rows, gating sensitive actions until the missing value is re-collected, and then restoring the column constraint once recovery is complete. It’s the lowest risk path because you never handle the compromised key again, but it does create friction for users and requires a plan to gather critical data back.

Option B (risky but sometimes necessary): Instead of discarding encrypted values, you run a one-off process that briefly uses the old key to preserve the data. This might be a local script, an isolated container, or another controlled job designed to touch the data once and then exit.

The process works by decrypting each record with the compromised key and immediately re-encrypting it with the new key. When the job is complete, you remove the old key and destroy the runner so it never lingers in your environment.

The upside is that users don’t lose data and don’t need to re-enter anything sensitive. The downside is that you’re still handling a key you know was exposed, which raises the risk profile. To make this approach safer, treat it as short-lived, auditable, and tightly controlled, and make sure backups or snapshots encrypted with the old key are also rotated or destroyed.

Painful but Necessary

Breach rotations are disruptive by nature, but they stop an attacker from continuing to forge or decrypt values.

Employee Termination

via GIPHY

When a trusted developer leaves, you should rotate secrets as proactive hygiene—even if no breach is suspected. People change jobs, laptops get repurposed, and access patterns shift. Rotating after a departure ensures that old credentials can’t be reused, accidentally or otherwise, down the line.

It’s also worth distinguishing between trusted and untrusted exits. If someone leaves on good terms, a safe/planned rotation is generally enough. But if you have reason to believe a developer might misuse access or walk away with secrets, you should treat it closer to a breach scenario—assume compromise and rotate aggressively.

Scheduled Rotation Cadence

Routine rotations should be predictable and documented. If you leave it up to chance, you’ll either never rotate, or you’ll be forced to do it in the middle of a crisis. The best practice is to set a fixed cadence and stick to it.

So when is a “good” time to perform them? Ideally, you pick a quiet spot in the calendar: away from major holidays, company-wide code freezes, or big releases; avoiding daylight-saving time changes; and during hours when your ops team is awake but traffic is low. For US-based teams, the second Tuesday of February is a great baseline—far enough from year-end chaos and before spring release season.

Planing

Preparation is half the battle. Make a clear list of:

• Which database columns are encrypted and will need to be re-encrypted.
• Which workflows rely on signed URLs and their typical TTL.
• Which user flows are most sensitive to disruption (login, checkout, API auth).

It also helps to line up a trusted test group — sometimes called a customer advisory board or beta group. These are customers (or internal champions) who know they’re part of the experiment, can walk through your app right after rotation, and give you fast feedback. Having a small, supportive group spot-check the critical flows makes it much less nerve-wracking than waiting for issues to pop up in the wild.

Process

A good rotation is more boring than dramatic. To make it that way:

• Run a dry run in staging the week before, with the same steps you’ll follow in production.
• Put a 48-hour change freeze around the event so no one sneaks in unrelated config changes.
• Keep a copy of the old APP_KEY, with Ghostable every change is versioned, so you can just roll back to a previous APP_KEY snapshot if needed.
• During and after the rotation, watch logs for login errors, decryption failures, or spikes in 500s.

And when everything checks out — grab a 🍺 with the team.