401 Unauthorized error when service account accesses Jira or Confluence API

Summary

When you use a service account to attempt to interact with the Jira and/or Confluence Cloud REST API, the response code 401 is returned, or the response indicates permission issues.

There are two types of API tokens:

• The general API Token

• The more specific API token with scope

Service accounts can only create scoped API tokens.

Solution

Why you're getting 401

A 401 Unauthorized response when using a service account's API token is typically caused by one of the following:

Ensure correct API endpoint URLs are used

As listed in our documentation on service accounts, scoped API tokens use a different URL structure when accessing the REST API. For example:

• Jira scoped token API: https://api.atlassian.com/ex/jira/<cloudId>/{api}

  • NOT: https://<your-domain>.atlassian.net/{api}

• Confluence scoped token API: https://api.atlassian.com/ex/confluence/<cloudid>/{api}

  • NOT: https://<your-domain>.atlassian.net/{api}

To correct errors returned by the API when using a service account's API token, use the appropriate URL format for the API token type.

Third-party integration errors

 Integrations may ask you to indicate a user account and an API token to connect to Jira. These integrations very likely don't "know" there are two types of tokens and two URL formats, and there is no way to distinguish them just from the token itself.

If an integration requires an API token and does not specify which type it needs, we can assume it is asking for a non-scoped API token. The API token with scopes, as generated for Service accounts, will not work in an integration unless specifically accounted for in the app's development. If you experience issues with integrations and Service Accounts, please reach out to the third-party app vendor to confirm whether they support API Tokens with scopes.

Please refer to CLOUD-12617: Add support for atlassian.net when sending web requests with scoped API tokens to avoid permission errors, which was raised requesting API Tokens with scopes to support the mysite.atlassian.net URL format.

How to confirm the fix

After making changes, verify that your scoped API token authenticates successfully by running a simple GET request against the api.atlassian.com endpoint.

For Confluence:

curl --request GET \ --url 'https://api.atlassian.com/ex/confluence/<cloudId>/wiki/rest/api/space' \ --user '<service-account-email>:<scoped-api-token>' \ --header 'Accept: application/json'

For Jira:

curl --request GET \ --url 'https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/myself' \ --user '<service-account-email>:<scoped-api-token>' \ --header 'Accept: application/json'

• A 200 response confirms the token, URL format, and scopes are all correct.

• A continued 401 means one of the following is still wrong:

  • The token's selected scopes don't include the permission needed for the endpoint being called — recreate the token with the appropriate scope(s).

  • The service account hasn't been granted access to the relevant Jira project or Confluence space — ask a site admin to verify the account's product access and permissions.