API token template URLs

Use template URLs to generate Cloudflare API tokens with pre-configured permissions. Template URLs allow you to share token requirements with users without manually selecting permissions in the dashboard.

Template URLs use query parameters to pre-fill the API token creation page in the Cloudflare dashboard. When a user opens a template URL, the dashboard automatically configures the specified permissions and settings.

Cloudflare supports template URLs for both user API tokens and account API tokens. For more information on the difference between these token types, refer to Account API tokens.

User token template URLs open the token creation form at the user profile level (/profile/api-tokens). Tokens created this way are owned by the user.

The basic template URL structure is:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_PERMISSIONS]&accountId=*&zoneId=all&name=[TOKEN_NAME]

Account token template URLs open the token creation form at the account level. Tokens created this way are owned by the account (service principal tokens) and are not tied to any individual user. Refer to Account API tokens for role and permission requirements.

The basic template URL structure is:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_PERMISSIONS]&name=[TOKEN_NAME]

The :account segment is a placeholder. When a user opens the URL, the dashboard prompts them to select an account if they have access to more than one.

Both user token and account token template URLs use the same permission encoding: a JSON array with the following structure.

[{ "key": "permission_name", "type": "read|edit|revoke|run|purge" }]

The two token types resolve these entries differently, as described in the following sections.

For account token URLs, each key can be either a short permission key (for example, dns) or a permission group ID. Using the permission group ID is the most reliable option, since it maps to exactly one group. Refer to Use permission group IDs.

For user token URLs, each key must be a short permission key that matches a group name exactly, and the type must be edit (not write), read, revoke, run, or purge. Permission group IDs are not supported, and any entry that does not match is dropped silently.

To address any permission group in an account token URL, including groups that do not have a short key in the permission reference, use its permission group ID as the key:

[{ "key": "82e64a83756745bbbb1c9c2701bf816b", "type": "edit" }]

Permission group IDs are the stable, canonical identifier for a permission group. They are the same IDs accepted by the Create token endpoint and the Cloudflare Terraform provider, so a template URL can pre-select any permission group by ID. Because the ID names one specific group, the type field is ignored when you pass an ID.

Combine multiple IDs in the same array, just as you would with short keys:

[
	{ "key": "e086da7e2179491d91ee5f35b3ca210a", "type": "edit" },
	{ "key": "7cf72faf220841aabcfdfab81c43c4f6", "type": "read" }
]

Because account token URLs create account-owned tokens, look up their permission group IDs with the account-scoped List permission groups endpoint. The request needs a token with the API Tokens Read account permission:

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/tokens/permission_groups" \
	--header "Authorization: Bearer <API_TOKEN>"

For user tokens, use the user-scoped endpoint instead, which returns the permission groups available to user tokens:

curl "https://api.cloudflare.com/client/v4/user/tokens/permission_groups" \
	--header "Authorization: Bearer <API_TOKEN>"

Each result includes the permission group id and name. The API token permissions reference also lists these IDs.

List the permissions your use case needs. Refer to the permission reference table.

Format your permissions as a JSON array:

[
	{ "key": "dns", "type": "edit" },
	{ "key": "analytics", "type": "read" }
]

Use a URL encoder to convert the JSON string:

%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D

For a user token, combine all components into the final template URL:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_JSON]&accountId=*&zoneId=all&name=Custom%20Token

For an account token, use the account-level path instead:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_JSON]&name=Custom%20Token

Use this table to find permission keys for your custom templates.

Use these ready-to-use template URLs for common scenarios. Each example provides both a user token URL and an account token URL.

Create tokens for DNS record management.

Create tokens for Workers, KV storage, and related services.

Create tokens for accessing analytics and logs.

Create tokens for Cloudflare Zero Trust management.

Follow these guidelines when creating and sharing template URLs.

• Principle of least privilege: Only request the minimum permissions necessary for your use case. This reduces security risks if a token is compromised.
• Use descriptive token names: Include clear, descriptive names in your template URLs to help users understand the token's purpose.
• Document token usage: Provide clear documentation about what each token is used for and how to revoke it when no longer needed.
• Regular token rotation: Encourage users to regularly rotate tokens and review permissions.
• Test before sharing: Always test template URLs in a staging environment before sharing them with users.

Review the list of common issues and solutions.

For account token URLs, when a template URL contains a key that cannot be resolved, or the permissionGroupKeys value is not valid JSON, the dashboard still opens the token creation form with whatever it could resolve and shows a notice naming the keys it could not apply. It does not redirect back to the token list, so a mistyped key surfaces in the form instead of failing silently.

For user token URLs, unresolved entries are dropped silently and no notice is shown, so verify each key against the permission reference before sharing the URL.

Additionally, review the checklist before sharing a template URL.

• All permission keys are correct
• JSON syntax is valid
• URL encoding is proper
• Token name is descriptive
• Permissions follow least privilege principle

• API token permissions
• Create API tokens
• Account API tokens
• API authentication