@@ -0,0 +1,13 @@
+---
+'@objectstack/platform-objects': patch
+'@objectstack/runtime': patch
+---
+
+feat: Setup → API Keys → Create Key offers the key's expiry, and a date past the policy's maximum is refused with the policy named
+
+Clause-②: yes
+Metadata-protocol: none
+
+Create Key asked only for a name, so every key silently got the default life the Authentication API key policy sets, and the list then showed an expiry the admin never chose. The `sys_api_key` action `create_api_key` now declares an optional `expires_at` param, the second body key `POST /api/v1/keys` already reads. Its help text says what an empty field means (the policy's Default key lifetime, 90 days unless changed) and that a date later than the policy's Maximum key lifetime is refused. The param has no literal default on purpose: an action param default is submitted verbatim, so a fixed date there would override the deployment's policy instead of following it. The reveal dialog now shows the expiry the key actually got, beside the key.
+
+The route behaviour is unchanged: an empty field gets the policy's default life, and a date past the maximum is refused `400 API_KEY_EXPIRY_TOO_LONG`, never clamped. That refusal's message now names the setting that decided it ("the Authentication API key policy's Maximum key lifetime is N days") next to the latest date allowed.
@@ -1123,12 +1123,18 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       create_api_key: {
         label: "Create Key",
         description: "Create a key for a script or integration. The key acts as you, with your access, in the organization you are working in now.",
+        params: {
+          expires_at: {
+            helpText: "Leave empty for the default lifetime set under Setup → Authentication → API keys (Default key lifetime, 90 days unless changed). A date later than the Maximum key lifetime there is refused."
+          }
+        },
         resultDialog: {
           title: "API key created",
           description: "Copy the key now — it is shown only once and cannot be recovered. If it leaks, revoke it and create a new one.",
           acknowledge: "I have saved the key",
           fields: {
-            key: "API Key"
+            key: "API Key",
+            expires_at: "Expires At"
           }
         }
       },
 
@@ -1123,12 +1123,18 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       create_api_key: {
         label: "Crear clave",
         description: "Crea una clave para un script o una integración. La clave actúa como tú, con tu acceso, en la organización en la que trabajas ahora.",
+        params: {
+          expires_at: {
+            helpText: "Déjelo vacío para usar la duración predeterminada de la clave definida en Configuración → Autenticación → Claves de API (90 días si no se ha cambiado). Una fecha posterior a la duración máxima de la clave definida allí se rechaza."
+          }
+        },
         resultDialog: {
           title: "Clave de API creada",
           description: "Copia la clave ahora: solo se muestra una vez y no se puede recuperar. Si se filtra, revócala y crea una nueva.",
           acknowledge: "He guardado la clave",
           fields: {
-            key: "Clave de API"
+            key: "Clave de API",
+            expires_at: "Caduca el"
           }
         }
       },
 
@@ -1123,12 +1123,18 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       create_api_key: {
         label: "キーを作成",
         description: "スクリプトや連携用のキーを作成します。キーはあなたとして、あなたのアクセス権で、現在作業中の組織で動作します。",
+        params: {
+          expires_at: {
+            helpText: "空欄のままにすると、「設定 → 認証 → API キー」のキーの既定の有効期間(変更していなければ 90 日)が使われます。そこにあるキーの最大有効期間より後の日付は拒否されます。"
+          }
+        },
         resultDialog: {
           title: "API キーを作成しました",
           description: "今すぐキーをコピーしてください。キーは一度しか表示されず、後から取得することはできません。漏えいした場合は失効させて新しいキーを作成してください。",
           acknowledge: "キーを保存しました",
           fields: {
-            key: "API キー"
+            key: "API キー",
+            expires_at: "有効期限"
           }
         }
       },
 
@@ -1123,12 +1123,18 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       create_api_key: {
         label: "创建密钥",
         description: "为脚本或集成创建密钥。该密钥以你的身份、按你的访问权限，在你当前所在的组织中生效。",
+        params: {
+          expires_at: {
+            helpText: "留空则使用「设置 → 身份验证 → API 密钥」中的默认密钥有效期(未修改时为 90 天)。晚于该处密钥最长有效期的日期会被拒绝。"
+          }
+        },
         resultDialog: {
           title: "API 密钥已创建",
           description: "请立即复制密钥——它只显示这一次，之后无法找回。如果泄露，请撤销它并创建新的密钥。",
           acknowledge: "我已保存密钥",
           fields: {
-            key: "API 密钥"
+            key: "API 密钥",
+            expires_at: "过期时间"
           }
         }
       },
 
@@ -145,8 +145,11 @@ describe('API Keys: Create Key through the existing mint route', () => {
   it('reveals the raw key in a result dialog, masked', () => {
     // The route answers `{ success, data: { key, … } }`; the console unwraps
     // `data` before resolving these paths, so the path is `key`, not `data.key`.
+    // Beside it, in plain text, the expiry the key actually got
+    // (`sys-api-key-create-expiry.test.ts`).
     expect(create?.resultDialog?.fields).toEqual([
       expect.objectContaining({ path: 'key', format: 'secret' }),
+      expect.objectContaining({ path: 'expires_at', format: 'text' }),
     ]);
   });
 
 
@@ -0,0 +1,60 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// sys_api_key's Create Key door offers the key's expiry, so the date in the
+// list is one the admin saw and could choose — not one that silently appeared.
+//
+// What this file pins, from source:
+//  - `create_api_key` declares exactly `name` (required) and `expires_at`
+//    (optional): the two body keys `POST /api/v1/keys` reads, and nothing the
+//    route ignores;
+//  - `expires_at` carries NO `defaultValue`: a param default is a literal
+//    submitted verbatim, so any date written here would override the
+//    deployment's Authentication API key policy instead of following it. Left
+//    empty, the route applies the policy's default life;
+//  - its help text names that policy, so the dialog says what an empty field
+//    means and that a later date than the maximum is refused;
+//  - the param resolves to a real datetime column on this object;
+//  - the reveal shows the expiry the key actually got, beside the key.
+//
+// The route half — the default applied when the field is empty, and a date
+// past the maximum refused `400 API_KEY_EXPIRY_TOO_LONG` with the policy
+// named, never clamped — is `packages/runtime/src/api-key-lifecycle.pin.test.ts`.
+import { describe, expect, it } from 'vitest';
+import { SysApiKey } from './sys-api-key.object.js';
+
+interface DeclaredParam {
+  field?: string;
+  name?: string;
+  required?: boolean;
+  defaultValue?: unknown;
+  helpText?: string;
+}
+
+const createKey = (SysApiKey.actions ?? []).find((a) => a.name === 'create_api_key') as
+  | { params?: DeclaredParam[]; resultDialog?: { fields?: Array<{ path: string }> } }
+  | undefined;
+
+describe('sys_api_key create_api_key — the expiry is declared on the dialog', () => {
+  it('declares exactly the two body keys the mint route reads', () => {
+    expect(createKey).toBeDefined();
+    const params = createKey!.params ?? [];
+    expect(params.map((p) => p.field ?? p.name)).toEqual(['name', 'expires_at']);
+    expect(params.find((p) => p.field === 'name')?.required).toBe(true);
+    expect(params.find((p) => p.field === 'expires_at')?.required ?? false).toBe(false);
+  });
+
+  it('leaves the default to the policy: no literal defaultValue on expires_at', () => {
+    const expiry = createKey!.params!.find((p) => p.field === 'expires_at')!;
+    expect(expiry.defaultValue).toBeUndefined();
+    expect(expiry.helpText).toContain('Default key lifetime');
+    expect(expiry.helpText).toContain('Maximum key lifetime');
+  });
+
+  it('resolves to a datetime column on this object', () => {
+    expect((SysApiKey.fields as Record<string, { type: string }>).expires_at.type).toBe('datetime');
+  });
+
+  it('reveals the expiry the key got, beside the key', () => {
+    expect(createKey!.resultDialog?.fields?.map((f) => f.path)).toEqual(['key', 'expires_at']);
+  });
+});
@@ -112,15 +112,30 @@ export const SysApiKey = ObjectSchema.create({
       // The route reads `name` (and an optional `expires_at`) and nothing else;
       // a key named nothing is stored as "API Key", so the name is required
       // here to keep the list readable.
+      //
+      // `expires_at` is offered so the expiry is a choice the admin sees, not
+      // a date that silently appears in the list. It stays optional and has
+      // NO `defaultValue`: a param default is a literal submitted verbatim,
+      // while the default life is the deployment's Authentication API key
+      // policy, which the route applies when the field is left empty. The
+      // help text names that policy, the route refuses (never clamps) a date
+      // past the policy's maximum (`API_KEY_EXPIRY_TOO_LONG`), and the reveal
+      // below shows the expiry the key actually got. The column's `readonly`
+      // is a form flag; an action param does not inherit it.
       params: [
         { field: 'name', required: true },
+        {
+          field: 'expires_at',
+          helpText: 'Leave empty for the default lifetime set under Setup → Authentication → API keys (Default key lifetime, 90 days unless changed). A date later than the Maximum key lifetime there is refused.',
+        },
       ],
       resultDialog: {
         title: 'API key created',
         description: 'Copy the key now — it is shown only once and cannot be recovered. If it leaks, revoke it and create a new one.',
         acknowledge: 'I have saved the key',
         fields: [
           { path: 'key', label: 'API Key', format: 'secret' },
+          { path: 'expires_at', label: 'Expires At', format: 'text' },
         ],
       },
     },
 
@@ -112,6 +112,10 @@ describe('[#23367] POST /keys — the default life and the ceiling', () => {
     expect(res.body.error.code).toBe('API_KEY_EXPIRY_TOO_LONG');
     // Located: the refusal names the latest date this signing may ask for.
     expect(res.body.error.message).toContain(new Date(NOW + 365 * DAY).toISOString());
+    // And the policy that refused it, by the setting's own label, so the
+    // admin knows which knob decided (the Create Key dialog's expiry field
+    // points at the same setting).
+    expect(res.body.error.message).toContain('Maximum key lifetime is 365 days');
     expect(rows).toHaveLength(0);
   });
 
 
@@ -240,9 +240,10 @@ export async function handleKeysRequest(
             return {
                 handled: true,
                 response: deps.error(
-                    `expires_at ${new Date(requestedMs).toISOString()} is further away than this deployment allows: an `
-                    + `API key lives at most ${policy.maxExpiryDays} days, so the latest expiry a key signed now may `
-                    + `have is ${latest}. Ask for that date or an earlier one, and rotate the key before it expires.`,
+                    `expires_at ${new Date(requestedMs).toISOString()} is further away than this deployment allows: the `
+                    + `Authentication API key policy's Maximum key lifetime is ${policy.maxExpiryDays} days, so the `
+                    + `latest expiry a key signed now may have is ${latest}. Ask for that date or an earlier one, and `
+                    + 'rotate the key before it expires.',
                     API_KEY_EXPIRY_TOO_LONG.status,
                     { code: API_KEY_EXPIRY_TOO_LONG.code },
                 ),