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.
If you use two-step verification to authenticate, your script needs to use a REST API token to authenticate.
What is an API token?
A primary use case for API tokens is to allow scripts to access REST APIs for Atlassian cloud apps using HTTP basic authentication.
Depending on the details of the HTTP library you use, you can replace your password with the token. 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-tokenIn this example, bot@serviceaccount.atlassian.com is the email address for the Atlassian account you're using to create the token.
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 by default. The scope for an API token defines the levels of access to data in your Atlassian apps. When you create an API token, you choose the access level for the API token. When you select scopes for the token, you give the token permissions to perform certain actions. You can only select scopes for Jira and Confluence.
You can allow APIs to view, write, and delete content in Jira and Confluence.
How to access the API
You need to use a base URL to make API requests: api.atlassian.com. Then you can construct a request to call the API for the app you’d like to access.
Create an API token with scopes
API tokens with an infinite lifespan pose a data security risk. To improve data security, by default, we set API tokens to expire in one year. When you create an API token, you can name it and set the expiration date for the token.
When you create an API token for a service account, the service account can authenticate and run scripts for the apps you give them access to. When you create a token you must select scopes for the token.
To create an API token for a service account:
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Directory> Service accounts.
For the service account, select Actions > Create credential.
Give your API token a name that describes what it does.
Select an expiration date for the API token.
Token expiration is 1 to 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’re done with this step. We recommend you save these best practices to keep your token safe:
Save your API token in a password manager.
You must create a service account before you can create a token for the service account.
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 admin.atlassian.com. Select your organization if you have more than one.
Select Directory> Service accounts.
For the service account, select Revoke.
Was this helpful?