Scoped API Tokens in Confluence Cloud
Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.
Summary
With the recent release of scoped API tokens for Confluence Cloud, users and admins can now create tokens with fine-grained permissions, enhancing security and compliance.
What are scoped API tokens?
Scoped API tokens allow you to specify what actions a token can perform in Confluence Cloud. Unlike classic tokens, which grant all permissions available to the user, scoped tokens restrict access to only the selected scopes, reducing risk if a token is compromised.
Why use scoped tokens?
Enhanced Security: Limit token permissions to only what is necessary.
Compliance: Meet organizational or regulatory requirements for least-privilege access.
Auditability: Easier to track and manage what each token can do.
Classic vs. Scoped, at a glance
Use a classic token when a script or integration needs broad, unrestricted access under your account. Use a scoped token whenever you can, especially for anything that will be stored, shared, or run outside your own machine — it limits the blast radius if the token ever leaks.
Key Differences from Classic Tokens
Classic tokens are unrestricted, and use site-specific URLs (https://<your_site>.atlassian.net/rest/api/)
Scoped tokens have specific permissions and are restricted by selected scopes. They use the
api.atlassian.comdomain instead of your site-specific URL.
Solution
How to create a scoped API token
When you select scopes for an API token, you give the token permission to perform certain actions. You can allow APIs to view, write, and delete content in Jira and Confluence. If you need to use an app that does not currently support API token with scopes, you can create a token without scopes. Each app offers different scope types, which you can read more about in our documentation on each:
You need to call the Atlassian API to use API tokens with scopes for Jira {{https://api.atlassian.com/ex/jira/{cloudId}} or Confluence {{https://api.atlassian.com/ex/confluence/{cloudId}}.
To create an API token with scopes:
Log in to https://id.atlassian.com/manage-profile/security/api-tokens.
Select Create API token with scopes.
Give your API token a name that describes its purpose.
Select an expiration date for the API token.
Token expiration must be between 1 and 365 days.
Select the app you’d like the API token to access.
Select the scopes to determine what the API token can do in Jira or Confluence.
Select Create.
Select Copy to clipboard, then paste the token to your script, or save it somewhere safe.
You can't recover the API token after you’ve completed this step. We recommend saving it in a password manager.
Verify it worked
After creating a scoped token, test it against exactly the scopes you assigned (both an allowed call and a call outside those scopes) to confirm the token is enforcing least-privilege access as expected before relying on it in production.
Treat any API token, scoped or classic, like a password: never commit it to source control, never share it in plain text, and rotate it if you suspect it has been exposed.
Use scoped tokens with Confluence Cloud REST API
Scoped tokens also require you to input your Cloud ID, which is unique to your cloud site and app combination. You can refer to this guide to get the CloudID: How to Find Your Atlassian Cloud Site's Cloud ID.
Once you have both the token and your Cloud ID, you can make requests to the API at this URL:
https://api.atlassian.com/ex/confluence/<cloudid>/<api>
Replace <cloudid> with your Confluence Cloud instance ID, and <api> with the specific endpoint you'd like to access.
For example, if you wanted to query the audit log for your Confluence site, an example request might look like the following:
curl --request GET --url 'https://api.atlassian.com/ex/confluence/<your_cloud_id>/wiki/rest/api/audit' --user ''<your_email>:<scoped_api_token>'' --header 'Accept: application/json'Was this helpful?