← Fundamentals / fundamentals / api / how-to

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. Creating account tokens requires Super Administrator or Administrator permissions.

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. Permissions are encoded as a JSON array with the following structure:

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

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.

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