@geolonia/geonicdb-cli 0.7.0 → 0.8.0

package/dist/index.js

@@ -785,6 +785,15 @@ var GdbClient = class _GdbClient {
   canRefresh() {
     return (!!this.refreshToken || !!this.clientId && !!this.clientSecret) && !this.apiKey;
   }
+  /** Check whether an error indicates an authentication/token problem that may be resolved by refreshing. */
+  static isTokenError(err) {
+    if (err.status === 401) return true;
+    if (err.status === 403) {
+      const msg = (err.message ?? "").toLowerCase();
+      return msg.includes("not assigned to any tenant") || msg.includes("invalid token");
+    }
+    return false;
+  }
   async performTokenRefresh() {
     if (this.refreshPromise) return this.refreshPromise;
     this.refreshPromise = this.doRefresh();
@@ -888,7 +897,7 @@ var GdbClient = class _GdbClient {
     try {
       return await this.executeRequest(method, path, options);
     } catch (err) {
-      if (err instanceof GdbClientError && err.status === 401 && this.canRefresh()) {
+      if (err instanceof GdbClientError && _GdbClient.isTokenError(err) && this.canRefresh()) {
         const refreshed = await this.performTokenRefresh();
         if (refreshed) {
           return await this.executeRequest(method, path, options);
@@ -917,7 +926,7 @@ var GdbClient = class _GdbClient {
     try {
       return await this.executeRawRequest(method, path, options);
     } catch (err) {
-      if (err instanceof GdbClientError && err.status === 401 && this.canRefresh()) {
+      if (err instanceof GdbClientError && _GdbClient.isTokenError(err) && this.canRefresh()) {
         const refreshed = await this.performTokenRefresh();
         if (refreshed) {
           return await this.executeRawRequest(method, path, options);
@@ -937,31 +946,6 @@ var GdbClientError = class extends Error {
 };
 
 // src/helpers.ts
-var SCOPES_HELP_NOTES = [
-  "Valid scopes:",
-  "  read:entities, write:entities, read:subscriptions, write:subscriptions,",
-  "  read:registrations, write:registrations, read:rules, write:rules,",
-  "  read:custom-data-models, write:custom-data-models,",
-  "  admin:users, admin:tenants, admin:policies, admin:oauth-clients,",
-  "  admin:api-keys, admin:metrics",
-  "",
-  "admin:X implies both read:X and write:X.",
-  "write:X does NOT imply read:X \u2014 specify both if needed."
-];
-var API_KEY_SCOPES_HELP_NOTES = [
-  "Valid scopes:",
-  "  read:entities, write:entities, read:subscriptions, write:subscriptions,",
-  "  read:registrations, write:registrations"
-];
-var VALID_PERMISSIONS = /* @__PURE__ */ new Set(["read", "write", "create", "update", "delete"]);
-function parsePermissions(raw) {
-  const permissions = raw.split(",").map((s) => s.trim()).filter(Boolean);
-  if (permissions.length === 0 || permissions.some((p) => !VALID_PERMISSIONS.has(p))) {
-    printError("--permissions must be a comma-separated list of: read, write, create, update, delete");
-    process.exit(1);
-  }
-  return permissions;
-}
 function resolveOptions(cmd) {
   const opts = cmd.optsWithGlobals();
   const config = loadConfig(opts.profile);
@@ -1027,6 +1011,8 @@ function withErrorHandler(fn) {
       }
       if (err instanceof GdbClientError && err.status === 401) {
         printError("Authentication failed. Please re-authenticate (e.g., `geonic auth login` or check your API key).");
+      } else if (err instanceof GdbClientError && err.status === 403 && /not assigned to any tenant|invalid token/i.test(err.message)) {
+        printError("Authentication failed. Please re-authenticate (e.g., `geonic auth login` or check your API key).");
       } else if (err instanceof GdbClientError && err.status === 403) {
         const detail = (err.ngsiError?.detail ?? err.ngsiError?.description ?? "").toLowerCase();
         if (detail.includes("entity type") || detail.includes("allowedentitytypes")) {
@@ -1335,16 +1321,16 @@ function addMeOAuthClientsSubcommand(me) {
       command: "geonic me oauth-clients list"
     }
   ]);
-  const create = oauthClients.command("create [json]").description("Create a new OAuth client").option("--name <name>", "Client name").option("--scopes <scopes>", "Allowed scopes (comma-separated)").option("--save", "Save credentials to config for automatic re-authentication").action(
+  const create = oauthClients.command("create [json]").description("Create a new OAuth client").option("--name <name>", "Client name").option("--policy <policyId>", "Policy ID to attach").option("--save", "Save credentials to config for automatic re-authentication").action(
     withErrorHandler(async (json, _opts, cmd) => {
       const opts = cmd.opts();
       let body;
       if (json) {
         body = await parseJsonInput(json);
-      } else if (opts.name || opts.scopes) {
+      } else if (opts.name || opts.policy) {
         const payload = {};
-        if (opts.name) payload.clientName = opts.name;
-        if (opts.scopes) payload.allowedScopes = opts.scopes.split(",").map((s) => s.trim());
+        if (opts.name) payload.name = opts.name;
+        if (opts.policy) payload.policyId = opts.policy;
         body = payload;
       } else {
         body = await parseJsonInput();
@@ -1367,8 +1353,7 @@ function addMeOAuthClientsSubcommand(me) {
         const tokenResult = await clientCredentialsGrant({
           baseUrl,
           clientId,
-          clientSecret,
-          scope: data.allowedScopes?.join(" ")
+          clientSecret
         });
         const config = loadConfig(globalOpts.profile);
         config.clientId = clientId;
@@ -1386,11 +1371,18 @@ function addMeOAuthClientsSubcommand(me) {
       printSuccess("OAuth client created.");
     })
   );
-  addNotes(create, SCOPES_HELP_NOTES);
+  addNotes(create, [
+    "Use --policy to attach an existing XACML policy to the OAuth client.",
+    "Manage policies with `geonic admin policies` commands."
+  ]);
   addExamples(create, [
     {
       description: "Create an OAuth client with flags",
-      command: "geonic me oauth-clients create --name my-ci-bot --scopes read:entities,write:entities"
+      command: "geonic me oauth-clients create --name my-ci-bot"
+    },
+    {
+      description: "Create with a policy attached",
+      command: "geonic me oauth-clients create --name my-ci-bot --policy <policy-id>"
     },
     {
       description: "Create and save credentials for auto-reauth",
@@ -1398,7 +1390,53 @@ function addMeOAuthClientsSubcommand(me) {
     },
     {
       description: "Create an OAuth client from JSON",
-      command: `geonic me oauth-clients create '{"clientName":"my-bot","allowedScopes":["read:entities"]}'`
+      command: `geonic me oauth-clients create '{"name":"my-bot","policyId":"<policy-id>"}'`
+    }
+  ]);
+  const update = oauthClients.command("update <clientId> [json]").description("Update an OAuth client").option("--name <name>", "Client name").option("--description <desc>", "Client description").option("--policy-id <policyId>", "Policy ID to attach (use 'null' to unbind)").option("--active", "Activate the OAuth client").option("--inactive", "Deactivate the OAuth client").action(
+    withErrorHandler(async (clientId, json, _opts, cmd) => {
+      const opts = cmd.opts();
+      let body;
+      if (json) {
+        body = await parseJsonInput(json);
+      } else if (opts.name || opts.description || opts.policyId !== void 0 || opts.active || opts.inactive) {
+        const payload = {};
+        if (opts.name) payload.name = opts.name;
+        if (opts.description) payload.description = opts.description;
+        if (opts.policyId !== void 0) payload.policyId = opts.policyId === "null" ? null : opts.policyId;
+        if (opts.active) payload.isActive = true;
+        if (opts.inactive) payload.isActive = false;
+        body = payload;
+      } else {
+        body = await parseJsonInput();
+      }
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "PATCH",
+        `/me/oauth-clients/${encodeURIComponent(String(clientId))}`,
+        { body }
+      );
+      outputResponse(response, format);
+      printSuccess("OAuth client updated.");
+    })
+  );
+  addExamples(update, [
+    {
+      description: "Rename an OAuth client",
+      command: "geonic me oauth-clients update <client-id> --name new-name"
+    },
+    {
+      description: "Attach a policy",
+      command: "geonic me oauth-clients update <client-id> --policy-id <policy-id>"
+    },
+    {
+      description: "Unbind policy",
+      command: "geonic me oauth-clients update <client-id> --policy-id null"
+    },
+    {
+      description: "Deactivate an OAuth client",
+      command: "geonic me oauth-clients update <client-id> --inactive"
     }
   ]);
   const del = oauthClients.command("delete <id>").description("Delete an OAuth client").action(
@@ -1417,6 +1455,25 @@ function addMeOAuthClientsSubcommand(me) {
       command: "geonic me oauth-clients delete <client-id>"
     }
   ]);
+  const regenerateSecret = oauthClients.command("regenerate-secret <clientId>").description("Regenerate the client secret of an OAuth client").action(
+    withErrorHandler(async (clientId, _opts, cmd) => {
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "POST",
+        `/me/oauth-clients/${encodeURIComponent(String(clientId))}/regenerate-secret`
+      );
+      printWarning("Save the new clientSecret now \u2014 it will not be shown again.");
+      outputResponse(response, format);
+      printSuccess("OAuth client secret regenerated.");
+    })
+  );
+  addExamples(regenerateSecret, [
+    {
+      description: "Regenerate client secret",
+      command: "geonic me oauth-clients regenerate-secret <client-id>"
+    }
+  ]);
 }
 
 // src/commands/me-api-keys.ts
@@ -1436,7 +1493,7 @@ function addMeApiKeysSubcommand(me) {
       command: "geonic me api-keys list"
     }
   ]);
-  const create = apiKeys.command("create [json]").description("Create a new API key").option("--name <name>", "Key name").option("--scopes <scopes>", "Allowed scopes (comma-separated)").option("--origins <origins>", "Allowed origins (comma-separated)").option("--entity-types <types>", "Allowed entity types (comma-separated)").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--permissions <perms>", "Comma-separated permissions (read, write, create, update, delete)").option("--save", "Save the API key to config for automatic use").action(
+  const create = apiKeys.command("create [json]").description("Create a new API key").option("--name <name>", "Key name").option("--policy <policyId>", "Policy ID to attach").option("--origins <origins>", "Allowed origins (comma-separated)").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--save", "Save the API key to config for automatic use").action(
     withErrorHandler(async (json, _opts, cmd) => {
       const opts = cmd.opts();
       if (opts.origins !== void 0) {
@@ -1449,14 +1506,12 @@ function addMeApiKeysSubcommand(me) {
       let body;
       if (json) {
         body = await parseJsonInput(json);
-      } else if (opts.name || opts.scopes || opts.origins || opts.entityTypes || opts.rateLimit || opts.dpopRequired !== void 0 || opts.permissions) {
+      } else if (opts.name || opts.policy || opts.origins || opts.rateLimit || opts.dpopRequired !== void 0) {
         const payload = {};
         if (opts.name) payload.name = opts.name;
-        if (opts.scopes) payload.allowedScopes = opts.scopes.split(",").map((s) => s.trim()).filter(Boolean);
+        if (opts.policy) payload.policyId = opts.policy;
         if (opts.origins) payload.allowedOrigins = opts.origins.split(",").map((s) => s.trim()).filter(Boolean);
-        if (opts.entityTypes) payload.allowedEntityTypes = opts.entityTypes.split(",").map((s) => s.trim()).filter(Boolean);
         if (opts.dpopRequired !== void 0) payload.dpopRequired = opts.dpopRequired;
-        if (opts.permissions) payload.permissions = parsePermissions(opts.permissions);
         if (opts.rateLimit) {
           const raw = opts.rateLimit.trim();
           if (!/^\d+$/.test(raw)) {
@@ -1506,20 +1561,13 @@ function addMeApiKeysSubcommand(me) {
     })
   );
   addNotes(create, [
-    ...API_KEY_SCOPES_HELP_NOTES,
-    "",
-    "Valid permissions: read, write, create, update, delete",
-    "  write = create + update + delete",
-    "  Permissions auto-generate XACML policies (allowedEntityTypes respected)."
+    "Use --policy to attach an existing XACML policy to the API key.",
+    "Manage policies with `geonic admin policies` commands."
   ]);
   addExamples(create, [
     {
-      description: "Create an API key with flags",
-      command: "geonic me api-keys create --name my-app --scopes read:entities --origins 'https://example.com'"
-    },
-    {
-      description: "Create with permissions (auto-generates XACML policy)",
-      command: "geonic me api-keys create --name my-app --permissions read,write --save"
+      description: "Create an API key with a policy",
+      command: "geonic me api-keys create --name my-app --policy <policy-id>"
     },
     {
       description: "Create and save API key to config",
@@ -1527,7 +1575,7 @@ function addMeApiKeysSubcommand(me) {
     },
     {
       description: "Create an API key from JSON",
-      command: `geonic me api-keys create '{"name":"my-app","allowedScopes":["read:entities"]}'`
+      command: `geonic me api-keys create '{"name":"my-app","policyId":"<policy-id>"}'`
     },
     {
       description: "Create an API key with rate limiting",
@@ -1538,6 +1586,77 @@ function addMeApiKeysSubcommand(me) {
       command: "geonic me api-keys create --name my-app --dpop-required"
     }
   ]);
+  const update = apiKeys.command("update <keyId> [json]").description("Update an API key").option("--name <name>", "Key name").option("--policy-id <policyId>", "Policy ID to attach (use 'null' to unbind)").option("--origins <origins>", "Allowed origins (comma-separated)").option("--rate-limit <n>", "Rate limit (requests per minute)").option("--dpop-required", "Require DPoP token binding").option("--no-dpop-required", "Disable DPoP requirement").option("--active", "Activate the API key").option("--inactive", "Deactivate the API key").action(
+    withErrorHandler(async (keyId, json, _opts, cmd) => {
+      const opts = cmd.opts();
+      if (opts.origins !== void 0) {
+        const parsed = opts.origins.split(",").map((s) => s.trim()).filter(Boolean);
+        if (parsed.length === 0) {
+          printError("allowedOrigins must contain at least 1 item. Use '*' to allow all origins.");
+          process.exit(1);
+        }
+      }
+      let body;
+      if (json) {
+        body = await parseJsonInput(json);
+      } else if (opts.name || opts.policyId !== void 0 || opts.origins !== void 0 || opts.rateLimit || opts.dpopRequired !== void 0 || opts.active || opts.inactive) {
+        const payload = {};
+        if (opts.name) payload.name = opts.name;
+        if (opts.policyId !== void 0) payload.policyId = opts.policyId === "null" ? null : opts.policyId;
+        if (opts.origins !== void 0) payload.allowedOrigins = opts.origins.split(",").map((s) => s.trim()).filter(Boolean);
+        if (opts.dpopRequired !== void 0) payload.dpopRequired = opts.dpopRequired;
+        if (opts.rateLimit) {
+          const raw = opts.rateLimit.trim();
+          if (!/^\d+$/.test(raw)) {
+            printError("--rate-limit must be a positive integer.");
+            process.exit(1);
+          }
+          const perMinute = Number(raw);
+          if (perMinute <= 0) {
+            printError("--rate-limit must be a positive integer.");
+            process.exit(1);
+          }
+          payload.rateLimit = { perMinute };
+        }
+        if (opts.active) payload.isActive = true;
+        if (opts.inactive) payload.isActive = false;
+        body = payload;
+      } else {
+        body = await parseJsonInput();
+      }
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "PATCH",
+        `/me/api-keys/${encodeURIComponent(String(keyId))}`,
+        { body }
+      );
+      outputResponse(response, format);
+      console.error("API key updated.");
+    })
+  );
+  addExamples(update, [
+    {
+      description: "Rename an API key",
+      command: "geonic me api-keys update <key-id> --name new-name"
+    },
+    {
+      description: "Attach a policy",
+      command: "geonic me api-keys update <key-id> --policy-id <policy-id>"
+    },
+    {
+      description: "Unbind policy",
+      command: "geonic me api-keys update <key-id> --policy-id null"
+    },
+    {
+      description: "Deactivate an API key",
+      command: "geonic me api-keys update <key-id> --inactive"
+    },
+    {
+      description: "Update from JSON",
+      command: `geonic me api-keys update <key-id> '{"name":"new-name","rateLimit":{"perMinute":60}}'`
+    }
+  ]);
   const del = apiKeys.command("delete <keyId>").description("Delete an API key").action(
     withErrorHandler(async (keyId, _opts, cmd) => {
       const client = createClient(cmd);
@@ -1556,6 +1675,149 @@ function addMeApiKeysSubcommand(me) {
   ]);
 }
 
+// src/commands/me-policies.ts
+function addMePoliciesSubcommand(me) {
+  const policies = me.command("policies").description("Manage your personal XACML policies");
+  const list = policies.command("list").description("List your personal policies").action(
+    withErrorHandler(async (_opts, cmd) => {
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest("GET", "/me/policies");
+      outputResponse(response, format);
+    })
+  );
+  addExamples(list, [
+    {
+      description: "List your personal policies",
+      command: "geonic me policies list"
+    }
+  ]);
+  const get = policies.command("get <policyId>").description("Get a personal policy by ID").action(
+    withErrorHandler(async (policyId, _opts, cmd) => {
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "GET",
+        `/me/policies/${encodeURIComponent(String(policyId))}`
+      );
+      outputResponse(response, format);
+    })
+  );
+  addExamples(get, [
+    {
+      description: "Get a personal policy by ID",
+      command: "geonic me policies get <policy-id>"
+    }
+  ]);
+  const create = policies.command("create [json]").description(
+    `Create a personal XACML policy
+
+Constraints (enforced server-side):
+  - priority is fixed at 100 (user role minimum)
+  - scope is 'personal' \u2014 not applied tenant-wide
+  - target is required
+  - data API paths only (/v2/**, /ngsi-ld/** etc.)
+
+Example \u2014 GET-only policy for /v2/**:
+  {
+    "policyId": "my-readonly",
+    "target": {
+      "resources": [{"attributeId": "path", "matchValue": "/v2/**", "matchFunction": "glob"}]
+    },
+    "rules": [
+      {"ruleId": "allow-get", "effect": "Permit", "target": {"actions": [{"attributeId": "method", "matchValue": "GET"}]}},
+      {"ruleId": "deny-others", "effect": "Deny"}
+    ]
+  }`
+  ).option("--policy-id <id>", "Policy ID (auto-generated UUID if omitted)").option("--description <text>", "Policy description").action(
+    withErrorHandler(async (json, _opts, cmd) => {
+      const opts = cmd.opts();
+      let body;
+      if (json) {
+        body = await parseJsonInput(json);
+      } else if (opts.policyId || opts.description) {
+        const payload = {};
+        if (opts.policyId) payload.policyId = opts.policyId;
+        if (opts.description) payload.description = opts.description;
+        body = payload;
+      } else {
+        body = await parseJsonInput();
+      }
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest("POST", "/me/policies", { body });
+      outputResponse(response, format);
+      printSuccess("Policy created.");
+    })
+  );
+  addNotes(create, [
+    "priority is always set to 100 by the server regardless of the value you specify.",
+    "Bind the policy to an API key or OAuth client with `geonic me api-keys update --policy-id` or `geonic me oauth-clients update --policy-id`."
+  ]);
+  addExamples(create, [
+    {
+      description: "Create a GET-only policy from inline JSON",
+      command: `geonic me policies create '{"policyId":"my-readonly","target":{"resources":[{"attributeId":"path","matchValue":"/v2/**","matchFunction":"glob"}]},"rules":[{"ruleId":"allow-get","effect":"Permit","target":{"actions":[{"attributeId":"method","matchValue":"GET"}]}},{"ruleId":"deny-others","effect":"Deny"}]}'`
+    },
+    {
+      description: "Create from a JSON file",
+      command: "geonic me policies create @policy.json"
+    },
+    {
+      description: "Create from stdin",
+      command: "cat policy.json | geonic me policies create"
+    }
+  ]);
+  const update = policies.command("update <policyId> [json]").description("Update a personal policy (partial update)").option("--description <text>", "Policy description").action(
+    withErrorHandler(async (policyId, json, _opts, cmd) => {
+      const opts = cmd.opts();
+      let body;
+      if (json) {
+        body = await parseJsonInput(json);
+      } else if (opts.description) {
+        body = { description: opts.description };
+      } else {
+        body = await parseJsonInput();
+      }
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "PATCH",
+        `/me/policies/${encodeURIComponent(String(policyId))}`,
+        { body }
+      );
+      outputResponse(response, format);
+      printSuccess("Policy updated.");
+    })
+  );
+  addExamples(update, [
+    {
+      description: "Update policy rules",
+      command: `geonic me policies update <policy-id> '{"rules":[{"ruleId":"allow-get","effect":"Permit"}]}'`
+    },
+    {
+      description: "Update from a JSON file",
+      command: "geonic me policies update <policy-id> @patch.json"
+    }
+  ]);
+  const del = policies.command("delete <policyId>").description("Delete a personal policy").action(
+    withErrorHandler(async (policyId, _opts, cmd) => {
+      const client = createClient(cmd);
+      await client.rawRequest(
+        "DELETE",
+        `/me/policies/${encodeURIComponent(String(policyId))}`
+      );
+      printSuccess("Policy deleted.");
+    })
+  );
+  addExamples(del, [
+    {
+      description: "Delete a personal policy",
+      command: "geonic me policies delete <policy-id>"
+    }
+  ]);
+}
+
 // src/commands/auth.ts
 function createLoginCommand() {
   return new Command("login").description("Authenticate and save token").option("--client-credentials", "Use OAuth 2.0 Client Credentials flow").option("--client-id <id>", "OAuth client ID").option("--client-secret <secret>", "OAuth client secret").option("--scope <scopes>", "OAuth scopes (space-separated)").option("--tenant-id <id>", "Tenant ID for scoped authentication").action(
@@ -1887,6 +2149,7 @@ function registerAuthCommands(program2) {
   ]);
   addMeOAuthClientsSubcommand(me);
   addMeApiKeysSubcommand(me);
+  addMePoliciesSubcommand(me);
   program2.addCommand(createLoginCommand(), { hidden: true });
   program2.addCommand(createLogoutCommand(), { hidden: true });
   const hiddenWhoami = new Command("whoami").description("Display current authenticated user").action(createMeAction());
@@ -3386,7 +3649,7 @@ function registerPoliciesCommand(parent) {
     }
   ]);
   const create = policies.command("create [json]").description(
-    'Create a new policy\n\nJSON payload examples:\n\n  Allow all entities:\n  {\n    "description": "Allow all entities",\n    "rules": [{"ruleId": "allow-all", "effect": "Permit"}]\n  }\n\n  Allow GET access to a specific entity type:\n  {\n    "description": "Allow GET access to Landmark entities",\n    "target": {\n      "resources": [{"attributeId": "entityType", "matchValue": "Landmark"}],\n      "actions": [{"attributeId": "method", "matchValue": "GET"}]\n    },\n    "rules": [{"ruleId": "permit-get", "effect": "Permit"}]\n  }\n\nTarget fields:\n  subjects   \u2014 attributeId: role, userId, email, tenantId\n  resources  \u2014 attributeId: path, entityType, entityId, entityOwner, tenantService, servicePath\n  actions    \u2014 attributeId: method (GET, POST, PATCH, DELETE)\n\nEach element: {attributeId, matchValue, matchFunction?}\n  matchFunction: "string-equal" (default) | "string-regexp" | "glob"\n\nPriority: higher number = higher priority (default: 0).\n  Custom policies (e.g. 100) override default role policies (0).\n\nDefault role policies (priority 0):\n  user \u2192 GET only, api_key \u2192 all Deny, anonymous \u2192 all Deny'
+    'Create a new policy\n\nJSON payload examples:\n\n  Allow all entities:\n  {\n    "description": "Allow all entities",\n    "rules": [{"ruleId": "allow-all", "effect": "Permit"}]\n  }\n\n  Allow GET access to a specific entity type:\n  {\n    "description": "Allow GET access to Landmark entities",\n    "target": {\n      "resources": [{"attributeId": "entityType", "matchValue": "Landmark"}],\n      "actions": [{"attributeId": "method", "matchValue": "GET"}]\n    },\n    "rules": [{"ruleId": "permit-get", "effect": "Permit"}]\n  }\n\nTarget fields:\n  subjects   \u2014 attributeId: role, userId, email, tenantId\n  resources  \u2014 attributeId: path, entityType, entityId, entityOwner, tenantService, servicePath\n  actions    \u2014 attributeId: method (GET, POST, PATCH, DELETE)\n\nEach element: {attributeId, matchValue, matchFunction?}\n  matchFunction: "string-equal" (default) | "string-regexp" | "glob"\n\nPriority: smaller value = higher precedence (e.g. priority 10 overrides user default at 100).\n  tenant_admin: minimum priority 10. user self-service (/me/policies): fixed at 100.\n\nDefault role policies (priority 100):\n  user \u2192 /v2/** and /ngsi-ld/** all methods Permit; other data APIs GET only\n  api_key \u2192 all Deny, anonymous \u2192 all Deny'
   ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
@@ -3542,7 +3805,7 @@ function registerOAuthClientsCommand(parent) {
     }
   ]);
   const create = oauthClients.command("create [json]").description(
-    'Create a new OAuth client\n\nJSON payload example:\n  {\n    "clientName": "my-app",\n    "allowedScopes": ["read:entities", "write:entities"]\n  }'
+    'Create a new OAuth client\n\nJSON payload example:\n  {\n    "name": "my-app",\n    "policyId": "<policy-id>"\n  }'
   ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
@@ -3558,7 +3821,7 @@ function registerOAuthClientsCommand(parent) {
   addExamples(create, [
     {
       description: "Create with inline JSON",
-      command: `geonic admin oauth-clients create '{"clientName":"my-app","allowedScopes":["read:entities","write:entities"]}'`
+      command: `geonic admin oauth-clients create '{"name":"my-app","policyId":"<policy-id>"}'`
     },
     {
       description: "Create from a JSON file",
@@ -3697,9 +3960,8 @@ function validateOrigins(body, opts) {
 function buildBodyFromFlags(opts) {
   const payload = {};
   if (opts.name) payload.name = opts.name;
-  if (opts.scopes) payload.allowedScopes = opts.scopes.split(",").map((s) => s.trim()).filter(Boolean);
+  if (opts.policy) payload.policyId = opts.policy;
   if (opts.origins) payload.allowedOrigins = opts.origins.split(",").map((s) => s.trim()).filter(Boolean);
-  if (opts.entityTypes) payload.allowedEntityTypes = opts.entityTypes.split(",").map((s) => s.trim()).filter(Boolean);
   if (opts.rateLimit) {
     const raw = String(opts.rateLimit).trim();
     if (!/^\d+$/.test(raw)) {
@@ -3714,7 +3976,6 @@ function buildBodyFromFlags(opts) {
     payload.rateLimit = { perMinute };
   }
   if (opts.dpopRequired !== void 0) payload.dpopRequired = opts.dpopRequired;
-  if (opts.permissions) payload.permissions = parsePermissions(opts.permissions);
   if (opts.tenantId) payload.tenantId = opts.tenantId;
   return payload;
 }
@@ -3760,14 +4021,14 @@ function registerApiKeysCommand(parent) {
       command: "geonic admin api-keys get <key-id>"
     }
   ]);
-  const create = apiKeys.command("create [json]").description("Create a new API key").option("--name <name>", "Key name").option("--scopes <scopes>", "Comma-separated scopes").option("--origins <origins>", "Comma-separated origins").option("--entity-types <types>", "Comma-separated entity types").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--permissions <perms>", "Comma-separated permissions (read, write, create, update, delete)").option("--tenant-id <id>", "Tenant ID").option("--save", "Save the API key to profile config").action(
+  const create = apiKeys.command("create [json]").description("Create a new API key").option("--name <name>", "Key name").option("--policy <policyId>", "Policy ID to attach").option("--origins <origins>", "Comma-separated origins").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--tenant-id <id>", "Tenant ID").option("--save", "Save the API key to profile config").action(
     withErrorHandler(async (json, _opts, cmd) => {
       const opts = cmd.opts();
       validateOrigins(void 0, opts);
       let body;
       if (json) {
         body = await parseJsonInput(json);
-      } else if (opts.name || opts.scopes || opts.origins || opts.entityTypes || opts.rateLimit || opts.dpopRequired !== void 0 || opts.permissions || opts.tenantId) {
+      } else if (opts.name || opts.policy || opts.origins || opts.rateLimit || opts.dpopRequired !== void 0 || opts.tenantId) {
         body = buildBodyFromFlags(opts);
       } else {
         body = await parseJsonInput();
@@ -3800,20 +4061,13 @@ function registerApiKeysCommand(parent) {
     })
   );
   addNotes(create, [
-    ...API_KEY_SCOPES_HELP_NOTES,
-    "",
-    "Valid permissions: read, write, create, update, delete",
-    "  write = create + update + delete",
-    "  Permissions auto-generate XACML policies (allowedEntityTypes respected)."
+    "Use --policy to attach an existing XACML policy to the API key.",
+    "Manage policies with `geonic admin policies` commands."
   ]);
   addExamples(create, [
     {
-      description: "Create an API key with flags",
-      command: "geonic admin api-keys create --name my-key --scopes read:entities,write:entities --origins '*'"
-    },
-    {
-      description: "Create with permissions (auto-generates XACML policy)",
-      command: "geonic admin api-keys create --name my-key --permissions read,write --origins '*'"
+      description: "Create an API key with a policy",
+      command: "geonic admin api-keys create --name my-key --policy <policy-id> --origins '*'"
     },
     {
       description: "Create an API key with DPoP required",
@@ -3824,7 +4078,7 @@ function registerApiKeysCommand(parent) {
       command: "geonic admin api-keys create @key.json --save"
     }
   ]);
-  const update = apiKeys.command("update <keyId> [json]").description("Update an API key").option("--name <name>", "Key name").option("--scopes <scopes>", "Comma-separated scopes").option("--origins <origins>", "Comma-separated origins").option("--entity-types <types>", "Comma-separated entity types").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--no-dpop-required", "Disable DPoP token binding").option("--permissions <perms>", "Comma-separated permissions (read, write, create, update, delete)").action(
+  const update = apiKeys.command("update <keyId> [json]").description("Update an API key").option("--name <name>", "Key name").option("--policy <policyId>", "Policy ID to attach").option("--origins <origins>", "Comma-separated origins").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--no-dpop-required", "Disable DPoP token binding").action(
     withErrorHandler(
       async (keyId, json, _opts, cmd) => {
         const opts = cmd.opts();
@@ -3832,7 +4086,7 @@ function registerApiKeysCommand(parent) {
         let body;
         if (json) {
           body = await parseJsonInput(json);
-        } else if (opts.name || opts.scopes || opts.origins || opts.entityTypes || opts.rateLimit || opts.dpopRequired !== void 0 || opts.permissions) {
+        } else if (opts.name || opts.policy || opts.origins || opts.rateLimit || opts.dpopRequired !== void 0) {
           body = buildBodyFromFlags(opts);
         } else {
           body = await parseJsonInput();
@@ -3851,11 +4105,8 @@ function registerApiKeysCommand(parent) {
     )
   );
   addNotes(update, [
-    ...API_KEY_SCOPES_HELP_NOTES,
-    "",
-    "Valid permissions: read, write, create, update, delete",
-    "  write = create + update + delete",
-    "  Permissions auto-generate XACML policies (allowedEntityTypes respected)."
+    "Use --policy to attach an existing XACML policy to the API key.",
+    "Manage policies with `geonic admin policies` commands."
   ]);
   addExamples(update, [
     {
@@ -3863,8 +4114,8 @@ function registerApiKeysCommand(parent) {
       command: "geonic admin api-keys update <key-id> --name new-name"
     },
     {
-      description: "Update permissions",
-      command: "geonic admin api-keys update <key-id> --permissions read,write"
+      description: "Attach a policy",
+      command: "geonic admin api-keys update <key-id> --policy <policy-id>"
     },
     {
       description: "Enable DPoP requirement",