Manage API tokens for service accounts
You can use an API token to authenticate a script with an Atlassian cloud app. You generate the token for your service account, then copy and paste it into a script. For each organization, you can create up to five service accounts for free. If you need more than five service accounts, consider a subscription to Atlassian Guard.
If you use two-step verification to authenticate, your script needs to use a REST API token to authenticate.
Service accounts are subject to the same permission and scope requirements as user accounts. Before setting up an API token, ensure that service accounts are assigned appropriate project roles, such as Administrators or Service Desk Team. This will enable the account to perform actions like submitting forms or running automation tasks.
What is an API token?
API tokens let your scripts access REST APIs for Atlassian cloud apps using HTTP basic authentication.
We use varied API token length rather than fixed length to ensure tokens are secure and reliable. If your script relies on a fixed API token length, check that it can handle a variable length.
What are scopes for API tokens?
API tokens for service accounts use scopes. Scopes define the level of access a token grants to your Atlassian app data.
When you create an API token, you choose what scopes it should have. By selecting scopes, you grant the token permission to perform certain actions.
For service accounts, you can choose scopes that allow APIs to read, write, and delete content in Jira and Confluence. Typical scopes include read:jira-work and write:jira-work. Use these scopes for tasks like fetching and updating form fields, submitting responses, or creating work items.
As a security best practice, select only the scopes your script requires. If you’re unsure, check the scope documentation.
If your service account is missing required permissions or scopes, you may encounter errors, such as:
401 Unauthorized404 Not Found"Issue does not exist or you do not have permission to see it."
Once you create an API token, you can’t modify its scopes. If you want to apply different scopes, you’ll need to create a new token.
Create an API token with scopes
API tokens with an infinite lifespan pose a data security risk. To improve data security, we set API tokens to expire in one year by default. When you create an API token, you can name it and set the expiration date for the token.
You must create a service account before you can create a token for the service account.
To create an API token for a service account:
Go to Atlassian Administration. Select your organization if you have more than one.
Select Directory > Service accounts.
Select the service account you want to create a credential for.
Select Create credentials.
Select API token, then select Next.
Give your API token a name that describes what it does. Select an expiration date for the API token. Token expiration can be between 1 and 365 days. Select Next.
Select scopes to determine what the API token can do in Jira or Confluence. Select Next.
Review your API token, then 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 completing this step. We recommend that you save your API token in a password manager as a best practice to keep your token safe.
Verify your API tokens
Once you have created your API token it is important to verify that it grants your script the access it needs. Make a test API call to check that the token has the proper scope and permission.
Test your token with a request
Tokens must always use the Platform API Gateway URLs beginning with api.atlassian.com to make API requests. You can construct a request to call the API for the app you’d like to access.
Here is an example of a properly formed URL for a request to the Jira app: https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/project/{project_key}
Authenticate your request
You can use Bearer token authentication or basic authentication in the HTTP header for APIs requiring the api.atlassian.com gateway.
Depending on the details of the HTTP library you use, you can replace your password with the token. Ensure the email corresponds to the service account, and use the API token in place of a password.
For example, when using curl, you could do something like this:
## URLs for API tokens with scopes for Jira and Confluence
curl -v https://api.atlassian.com/ex/jira/{cloudId} --user bot@serviceaccount.atlassian.com:my-api-token
curl -v https://api.atlassian.com/ex/confluence/{cloudId} --user bot@serviceaccount.atlassian.com:my-api-tokenFind required information
In the example above, bot@serviceaccount.atlassian.com is the email address for the Atlassian account you're using to create the token.
A Cloud ID is a unique identifier assigned to each Atlassian Cloud site (instance). It's used for app development, management, and certain administrative tasks and is required for constructing API requests using api.atlassian.com. The Cloud ID is different from an Organization ID, which refers to a grouping of multiple Cloud sites or products.
To find your Cloud ID:
Go to
admin.atlassian.com.Locate the string after
/s/in your admin URL or response, such as1a11d016-8984-4c3e-b9ab-142dd06acb1b.
Avoid using your Organization ID, as this will result in errors like 404 Not Found or failed API requests.
Troubleshoot a failed request
Use the checklists below to verify your API tokens and resolve any issues.
Check your endpoint format
Check you're using your cloud ID (and not your organization ID) in your API endpoint.
Check your string has no typos or spaces.
Confirm token and account status
Make sure the API token is active and has not been revoked.
Check that the service account is not deactivated or suspended.
Verify API token scopes
Check the token's validity, expiration date, and proper encoding (Base64 if using an email:token format).
Ensure that the proper scopes for your use case (read, write, admin) were selected when it was created. If you are unsure which scopes are needed, refer to the pages:
Check service account app access
Make sure the service account is included in the relevant groups that grant app access.
If a normal user account works but the service account doesn’t, you can compare their group memberships and permissions to identify any differences.
Use Atlassian's permission helper to confirm the service account has the required project permissions.
Check Jira space and work item permissions
Make sure you’ve added the service account to the correct space roles.
Confirm the service account has the necessary permissions for the actions it needs to perform.
Use the permissions helper in Jira to check if the service account has access to the specific work item or space. Go to Space settings > Permissions > Permission Helper, and enter the service account’s email and the issue key.
Revoke an API token
When you revoke a token it no longer works and we permanently remove it from your account. If you revoke an existing API token, you can replace it with a new token. It takes up to 10 minutes for the token to be revoked.
To revoke an API token:
Go to Atlassian Administration. Select your organization if you have more than one.
Select Directory > Service accounts.
Select the service account you want to revoke a token from.
In Credentials, select Revoke for the token.
Notes about service accounts
Service accounts cannot be used for interactive login to the Atlassian Cloud UI.
Some features, such as group syncing from identity providers (for example, OKTA), may not be available for service accounts.
Service accounts are subject to the same permission and scope requirements as regular users.
You can create up to five service accounts for free for each organization. If you need more, consider a subscription to Atlassian Guard.
Was this helpful?