Scoped API Tokens in Confluence Cloud
Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.
Summary
Scoped API tokens let you limit what a token can do in Confluence Cloud by selecting specific scopes. Use a scoped token whenever you can, especially when you store, share, or run it outside your own machine.
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.
Use a classic token when a script or integration needs broad, unrestricted access under your account. Use a scoped token whenever you can. It limits access to the scopes you select and reduces the risk if the token is compromised.
Token type | Access | API URL |
Classic token | Broad, unrestricted access under your account |
|
Scoped token | Access limited to the scopes you select |
|
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:
Each app supports different scope types. Use the scope documentation for the app you want the API token to access. If an app does not support API tokens with scopes, create a token without scopes instead.
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:
Sign in to your Atlassian account and open your API token settings.
Select Create API token with scopes.
Enter a name that describes the token's purpose.
Select an expiration date between one and 365 days.
Select the app that the API token can access.
Select the scopes that define what the API token can do in Jira or Confluence.
Select Create.
Select Copy to clipboard, then paste the token into your script or save it somewhere safe.
Important: You can't recover the token after you complete this step. Save it in a password manager. Treat every 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 that it has been exposed.
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.
Use scoped tokens with Confluence Cloud REST API
Scoped tokens require the Cloud ID for your Confluence Cloud site and app combination. Obtain your Cloud ID before making a request.
Use this URL structure for Confluence Cloud API requests:
https://api.atlassian.com/ex/confluence/<cloudid>/<api>
Replace <cloudid> with your Confluence Cloud site ID and <api> with the endpoint you want to access. For example, this request queries the audit log:
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?