[Fundamentals] API token permission ID (#23973)

* use permission ID instead of name

* Update src/content/docs/fundamentals/api/how-to/create-via-api.mdx

Co-authored-by: Pedro Sousa <[email protected]>

---------

Co-authored-by: Pedro Sousa <[email protected]>

Author: ranbel

src/content/docs/fundamentals/api/how-to/create-via-api.mdx

@@ -7,7 +7,7 @@ sidebar:
 
 ---
 
-import { Render, Tabs, TabItem } from "~/components"
+import { Render, Tabs, TabItem, APIRequest } from "~/components"
 
 Generate new API tokens on the fly via the API. Before you can do this, you must create an API token in the Cloudflare dashboard that can create subsequent tokens.
 
@@ -100,7 +100,40 @@ For user resources, you can only reference yourself, which is denoted as:`"com.c
 
 #### Permission groups
 
-Determine what permission groups should be applied. Refer to the full list of permission groups either in [the documentation](/fundamentals/api/reference/permissions/) or fetch the permission groups [via the API](/api/resources/user/subresources/tokens/subresources/permission_groups/methods/list/). It is only required to pass the `id` of the permission group in the policy. Permission groups are scoped to specific resources, so a permission group in a policy will only apply to the resource type it is scoped for.
+Add permission groups to the API token by specifying their `id` values. We recommend using `id` as the key for interacting with Cloudflare APIs; the permission `name` is cosmetic and subject to change. Permission groups are scoped to specific resources (user, account, or zone), so a permission group in a policy will only apply to the resource type it is scoped for.
+
+To fetch all available permission groups and their IDs, use the [List permission groups](/api/resources/user/subresources/tokens/subresources/permission_groups/methods/list/) endpoint:
+
+<APIRequest
+  path="/user/tokens/permission_groups"
+  method="GET"
+/>
+
+```json output
+{
+  "result": [
+    {
+      "id": "19637fbb73d242c0a92845d8db0b95b1",
+      "name": "AI Audit Read",
+      "description": "Grants access to reading AI Audit",
+      "scopes": [
+        "com.cloudflare.api.account.zone"
+      ]
+    },
+    {
+      "id": "1ba6ab4cacdb454b913bbb93e1b8cb8c",
+      "name": "AI Audit Write",
+      "description": "Grants access to reading and editing AI Audit",
+      "scopes": [
+        "com.cloudflare.api.account.zone"
+      ]
+    },
+    // (...)
+	]
+}
+```
+
+
 
 ### 2. Define the restrictions