@@ -0,0 +1,7 @@
+---
+'@objectstack/core': patch
+---
+
+Clause-②: no
+
+A call with a revoked API key no longer hears "a revoked key never works again". The key row's own Restore API Key action clears the flag and the same key works again at once, so the `403 API_KEY_REVOKED` message now says the key was revoked, that its owner or a platform administrator can restore it (the Restore API Key action on the API Keys list), and otherwise to create a new key (`POST /api/v1/keys`, or the API Keys page) and replace this one wherever it is configured. The code, the status, the fields the refusal carries and the expired and inactive messages are unchanged. The error catalog's `API_KEY_REVOKED` Fix line says the same.
@@ -446,7 +446,7 @@ result set — a response indistinguishable from a successful query.
 
 ### `API_KEY_REVOKED`
 **Cause:** The API key was revoked by its owner or an administrator.  
-**Fix:** Create a new key and replace this one wherever it is configured. A revoked key never works again.  
+**Fix:** Ask the key's owner or a platform administrator to restore it (the Restore API Key action on the API Keys list); the same key then works again at once. Otherwise create a new key and replace this one wherever it is configured.  
 **Retry:** `no_retry`
 
 These three are answered on every endpoint that accepts an API key: the endpoints the runtime serves (the MCP HTTP endpoint among them), the REST data API, the settings, file-download, datasource admin and share-link routes, the marketplace install routes and the MCP stdio transport. An unknown key is always the generic 401.
 
@@ -17,7 +17,9 @@
  *    stamped onto `expires_at` when admitted, and refused with that date after;
  *  - an admitted (or held) call stamps `last_used_at`, at most once an hour,
  *    and a stamp failure never fails the request and is said once;
- *  - each number is the source's, so a changed setting changes the verdict.
+ *  - each number is the source's, so a changed setting changes the verdict;
+ *  - the revoked refusal names the declared restore action beside the new-key
+ *    road and never claims the key is gone for good.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -298,3 +300,33 @@ describe('[#23367] resolveAuthzContext raises the refusal, branded, and never fa
     expect({ userId: ctx.userId, credential: ctx.credential }).toEqual({ userId: OWNER, credential: 'api_key' });
   });
 });
+
+describe('[#23944] the revoked refusal agrees with the declared restore action', () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => { warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined); });
+  afterEach(() => { warn.mockRestore(); });
+
+  it('names the restore road and the new-key road, and never says the key is gone for good', async () => {
+    const err = await resolveAuthzContext({
+      ql: makeQl({ revoked: true }),
+      headers: headers(),
+      nowMs: NOW,
+      userAuthGates: undefined,
+      apiKeyLifecycle: policy(),
+    }).catch((e) => e);
+
+    // The envelope is untouched; only the prose moved.
+    expect(isApiKeyLifecycleRefusalError(err)).toBe(true);
+    expect({ code: err.code, status: err.status }).toEqual({ code: 'API_KEY_REVOKED', status: 403 });
+
+    // `sys_api_key` declares `restore_api_key`, whose PATCH `{ revoked: false }`
+    // brings the same key back: a refusal that says "never works again" is
+    // contradicted by the product's own action. Name the action by its label,
+    // name who may run it, and keep rotation as the other road.
+    expect(err.message).toContain('osk_lifecycl');
+    expect(err.message).toContain('Restore API Key');
+    expect(err.message).toMatch(/owner or a platform administrator can restore it/);
+    expect(err.message).toContain('POST /api/v1/keys');
+    expect(err.message).not.toMatch(/never|permanent|forever|for good/i);
+  });
+});
@@ -306,7 +306,16 @@ function lifecycleRefusalOf(
   if (row.revoked === true || row.revoked === 1) {
     return {
       code: API_KEY_REVOKED_REFUSAL.code,
-      message: `${label} was revoked, and a revoked key never works again. ${API_KEY_REMEDY}`,
+      // Revocation is the `revoked` flag, and `restore_api_key` clears it again
+      // (`sys_api_key`'s own row action): the key works at once, no re-issue.
+      // Who may clear it is who may set it — the key's owner (own rows, `revoked`
+      // alone) and a platform administrator (any row) — so the text names those
+      // two and never claims the key is gone for good. Rotation stays the other
+      // road, for a key that should not come back.
+      message:
+        `${label} was revoked. Its owner or a platform administrator can restore it (the Restore API Key action `
+        + 'on the API Keys list); otherwise create a new key (POST /api/v1/keys, or the API Keys page) and replace '
+        + 'this one wherever it is configured.',
       ...ids,
     };
   }