From 0640f13b5ca991150b31fc201ce643e5fbb5c75c Mon Sep 17 00:00:00 2001 From: Ranbel Sun Date: Fri, 25 Jul 2025 14:25:43 -0400 Subject: [PATCH 1/2] use permission ID instead of name --- .../api/how-to/create-via-api.mdx | 37 ++++++++++++++++++- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/src/content/docs/fundamentals/api/how-to/create-via-api.mdx b/src/content/docs/fundamentals/api/how-to/create-via-api.mdx index 81c63fa9b8f130a..613354bbcb71373 100644 --- a/src/content/docs/fundamentals/api/how-to/create-via-api.mdx +++ b/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: + + + +```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 From ca0da2c9fb152c66ce5c1cc4a82943af97e915bd Mon Sep 17 00:00:00 2001 From: ranbel <101146722+ranbel@users.noreply.github.com> Date: Mon, 28 Jul 2025 10:26:00 -0400 Subject: [PATCH 2/2] Update src/content/docs/fundamentals/api/how-to/create-via-api.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> --- src/content/docs/fundamentals/api/how-to/create-via-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/fundamentals/api/how-to/create-via-api.mdx b/src/content/docs/fundamentals/api/how-to/create-via-api.mdx index 613354bbcb71373..d2097b23675ac6e 100644 --- a/src/content/docs/fundamentals/api/how-to/create-via-api.mdx +++ b/src/content/docs/fundamentals/api/how-to/create-via-api.mdx @@ -128,7 +128,7 @@ To fetch all available permission groups and their IDs, use the [List permission "com.cloudflare.api.account.zone" ] }, - // (...) + // (...) ] } ```