Making Calls to API

Put the code you received from Implementing OAuth 2.0 (3LO) into the Authorization header prefixed by Bearer as shown below.

Requests that use OAuth 2.0 (3LO) are made via api.atlassian.com (not https://your-domain.atlassian.net). See the example below:

1
2
curl --request GET \
  --url https://api.atlassian.com/oauth/token/accessible-resources \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

Cloud ID

Certain API calls, especially calls attached to a specific site (e.g. your-domain.atlassian.net), require a Cloud ID to denote which site it should be called on.

Retrieving Cloud ID

Some requests require a cloud id for calls which affect specific sites. The accessible-resources operation shown above retrieves all the sites that this token is valid for and their cloudId value denoted as id in the response.

Here's a few example responses:

• A Jira site:

1
2
[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user",
      "manage:jira-configuration"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

• A Jira Service Management site:

1
2
[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user",
      "read:servicedesk-request"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

• A Confluence site:

1
2
[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:confluence-content",
      "read:confluence-content.all",
      "manage:confluence-configuration"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

Using the Cloud ID

Requests using OAuth 2.0 (3LO) with a cloudId use the following structure:

• Jira apps: https://api.atlassian.com/ex/jira/{cloudid}/{api}
• Confluence apps: https://api.atlassian.com/ex/confluence/{cloudid}/{api}

where:

• {cloudid} is the cloudid for your site that you obtained in the previous step. For example, 11223344-a1b2-3b33-c444-def123456789.
• {api} is the base path and name of the API. For example:
  • /rest/api/2/project for the project endpoint in the Jira REST API.
  • /rest/servicedeskapi/request for the request endpoint in the Jira Service Management REST API.
  • /rest/api/space for the space endpoint in the Confluence REST API.

Your request URL should look something like this (using the example cloudid and Jira API above):

https://api.atlassian.com/ex/jira/11223344-a1b2-3b33-c444-def123456789/rest/api/2/project

Check Site Access for the App

An authorization grant is when a user consents to your app accessing a specific site and APIs within that site (via scopes). This can change when either of the following occur:

• The user revokes the grant for the site.
• The user consents to a new grant for the site. The scopes in the new grant override the scopes in the existing grant.

Therefore, since a grant can change over time, it's important that you check your app's access to a site and its APIs when calling the site's APIs. To check this, call the accessible-resources endpoint on https://auth.atlassian.com (you used this endpoint in a previous step to get the cloudid for your site).

TODO: add link to swagger for accessible-resource operation