OAuth 2.0 authentication

Retrieving username and Confluence (Cloud) URL

1. Log in to your account from the Confluence (Cloud). Note the username you logged in with. You will need this later to connect to Amazon Q.

2. From your Confluence (Cloud) home page, note your Confluence (Cloud) URL from your Confluence browser URL. For example: https://example.atlassian.net. You will need this later to both configure your OAuth 2.0 token and connect to Amazon Q.

Configuring an OAuth 2.0 app integration

1. Log in to your account from the Atlassian Developer page.

2. Select the profile icon from the top-right corner. Then, from the dropdown menu that opens, select Developer Console.

   

3. From the Welcome page, select Create and then select OAuth 2.0 integration.

   

4. On the Create a new OAuth 2.0 (3LO) integration page, for Name, enter a name for the OAuth 2.0 application you are creating. Then, select the I agree to be bound by Atlassian's developer terms checkbox, and select Create.

   

   The console will display a summary page outlining the details of the OAuth 2.0 app created.

   

5. From the left navigation menu, choose Authorization.

6. From the Authorization page, choose Add to add OAuth 2.0 (3LO) to your app.

   

7. On the OAuth 2.0 authorization code grants (3LO) for apps, enter the Confluence (Cloud) URL you copied as the Callback URL and then choose Save changes.

   

8. From the Authorization URL generator section that appears, choose Add APIs to add APIs to your app. This will redirect you to the Permissions page.

9. On the Permissions page, for Scopes, navigate to User Identity API. Select Add, and then select Configure.

   

10. On the User Identity API page, choose Edit Scopes, and the add the following read scopes:

    • read:me – View active user profile

    • read:account – View user profiles

    

    Then, select Save.

11. Return to the Permissions page. From Scopes, navigate to Confluence API. Select Add, and the select Configure.

    

12. Navigate to the Granular scopes page.

    

    Then, choose Edit Scopes, and the add the following read scopes:

    • read:content:confluence – View detailed contents

    • read:content-details:confluence – View content details

    • read:space-details:confluence – View space details

    • read:audit-log:confluence – View audit records

    • read:page:confluence – View pages

    • read:attachment:confluence – View and download content attachments

    • read:blogpost:confluence – View blogposts

    • read:custom-content:confluence – View custom content

    • read:comment:confluence – View comments

    • read:template:confluence – View content templates

    • read:label:confluence – View labels

    • read:watcher:confluence – View content watchers

    • read:group:confluence – View groups

    • read:relation:confluence – View entity relationships

    • read:user:confluence – View user details

    • read:configuration:confluence – View Confluence settings

    • read:space:confluence – View space details

    • read:space.permission:confluence – View space permissions

    • read:space.property:confluence – View space properties

    • read:user.property:confluence – View user properties

    • read:space.setting:confluence – View space settings

    • read:analytics.content:confluence – View analytics for content

    • read:content.permission:confluence – Check content permissions

    • read:content.property:confluence – View content properties

    • read:content.restriction:confluence – View content restrictions

    • read:content.metadata:confluence – View content summaries

    • read:inlinetask:confluence – View tasks

    • read:task:confluence – View tasks

    • read:permission:confluence – View content restrictions and space permissions

    • read:whiteboard:confluence – View whiteboards

    • read:app-data:confluence – Read app data

    • (Optional) read:database:confluence – Read database

    • (Optional) read:embed:confluence – Read embeddings

    • (Optional) read:folder:confluence – Read folders

    • (Optional) read:email-address:confluence – Read email addresses

    Then, select Save.

Retrieving Confluence (Cloud) client ID and client secret

• From the left navigation menu, choose Settings. Then, scroll down to Authentication details section and copy and save the following in a text editor of your choice:

  • Client ID – You will enter this as App key in the Amazon Q console.

  • Client Secret – You will enter this as App secret in the Amazon Q console.

  

  You will need these to generate your Confluence (Cloud) OAuth 2.0 token and also to connect Amazon Q to Confluence (Cloud).

Generating your Confluence (Cloud) access token

1. Log in to your account from the Atlassian Developer page.

2. Open the OAuth 2.0 app you want to generate a refresh token for.

3. From the left navigation menu, choose Authorization again. Then, for OAuth 2.0 (3LO), choose Configure.

4. From the Authorization page, from Authorization URL generator, from Granular Confluence API authorization URL, copy the URL and save it in a text editor of your choice.

   

   The URL is of the following format:

   https://auth.atlassian.com/authorize?
   audience=api.atlassian.com 
   &client_id=YOUR_CLIENT_ID
   &scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO
   &redirect_uri=https://YOUR_APP_CALLBACK_URL
   &state=YOUR_USER_BOUND_VALUE 
   &response_type=code
   &prompt=consent

5. In the saved authorization URL, update the state=${YOUR_USER_BOUND_VALUE} parameter value to any text of your choice. For example, state=sample_text.

   For more information, see What is the state parameter used for? in Atlassian Support.

6. Open a web browser of your choice. Then, paste the authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select Accept.

   

   You will be returned to your Confluence (Cloud) home page.

7. Copy the URL of the Confluence (Cloud) home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) access token. The whole section after code= is the authorization code.

8. Navigate to Postman.

   If you don't have Postman, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:

   curl --location 'https://auth.atlassian.com/oauth/token' \
   --header 'Content-Type: application/json' \
   --data '{"grant_type": "authorization_code",
   "client_id": "YOUR_CLIENT_ID",
   "client_secret": "YOUR_CLIENT_SECRET",
   "code": "AUTHORIZATION_CODE",
   "redirect_uri": "YOUR_CALLBACK_URL"}'

9. On the Postman home page, select POST as the method, and then enter the following URL in the Enter URL or paste text box: https://auth.atlassian.com/oauth/token.

10. Then, select Body from the menu, and select raw JSON.

    

11. In the text box, enter the following code extract, replacing the fields with your credential values:

    {"grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "YOUR_AUTHORIZATION_CODE",
    "redirect_uri": "https://YOUR_APP_CALLBACK_URL"} 
                    

12. Then, select Send. If everything is configured correctly, Postman will return an access-token. Copy the access token and save it using a text editor of your choice. You will need it to connect Confluence (Cloud) to Amazon Q.

Generating an Confluence (Cloud) refresh token

1. Log in to your account from the Atlassian Developer page.

2. Open the OAuth 2.0 app you want to generate a refresh token for.

3. From the left navigation menu, choose Authorization again. Then, for OAuth 2.0 (3LO), choose Configure.

4. From the Authorization page, from Authorization URL generator, from Granular Confluence API authorization URL, copy the URL and save it in a text editor of your choice.

   

5. In the saved authorization URL, update the state=${YOUR_USER_BOUND_VALUE} parameter value to any text of your choice. For example, state=sample_text.

   For more information, see What is the state parameter used for? in Atlassian Support.

6. Then, add the following text at the end of the scope value in your authorization URL: %20offline_access and copy it. For example:

   https://auth.atlassian.com/authorize?
   audience=api.atlassian.com 
   &client_id=YOUR_CLIENT_ID
   &scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO%20offline_access
   &redirect_uri=https://YOUR_APP_CALLBACK_URL
   &state=YOUR_USER_BOUND_VALUE 
   &response_type=code
   &prompt=consent

7. Open a web browser of your choice and paste the modified authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select Accept.

   

   You will be returned to the Confluence (Cloud) console.

8. Copy the URL of the Confluence (Cloud) home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) refresh token. The whole section after code= is the authorization code.

9. Navigate to Postman.

   If you don't have Postman, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:

   curl --location 'https://auth.atlassian.com/oauth/token' \
   --header 'Content-Type: application/json' \
   --data '{"grant_type": "authorization_code",
   "client_id": "YOUR CLIENT ID",
   "client_secret": "YOUR CLIENT SECRET",
   "code": "AUTHORIZATION CODE",
   "redirect_uri": "YOUR CALLBACK URL"}'

10. On the Postman home page, select POST as the method, and then enter the following URL in the Enter URL or paste text box: https://auth.atlassian.com/oauth/token.

11. Then, select Body from the menu, and select raw JSON.

    

12. In the text box, enter the following code extract, replacing the fields with your credential values:

    {"grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "YOUR_AUTHORIZATION_CODE",
    "redirect_uri": "https://YOUR_APP_CALLBACK_URL"} 
                    

13. Then, select Send. If everything is configured correctly, Postman will return an refresh-token.

    Copy the refresh token and save it using a text editor of your choice. You will need it to connect Confluence (Cloud) to Amazon Q.

Generating an Confluence (Cloud) access token-refresh token pair

1. Copy the refresh token you generated following the steps in Step 5: Generating a Confluence (Cloud) refresh token.

2. Navigate to Postman.

   If you don't have Postman, you can also choose to use cURL to generate a new Confluence (Cloud) access token. Use the following cURL command to do so:

   curl --location 'https://auth.atlassian.com/oauth/token' \
   --header 'Content-Type: application/json' \
   --data '{"grant_type": "refresh_token",
   "client_id": "YOUR_CLIENT_ID",
   "client_secret": "YOUR_CLIENT_SECRET",
   "refresh_token": "YOUR_REFRESH_TOKEN"}'

3. On the Postman home page, select POST as the method, and then enter the following URL in the Enter URL or paste text box: https://auth.atlassian.com/oauth/token.

4. Then, select Body from the menu, and select raw JSON.

   

5. In the text box, enter the following code extract, replacing the fields with your credential values:

   {"grant_type": "refresh_token",
   "client_id": "YOUR_CLIENT_ID",
   "client_secret": "YOUR_CLIENT_SECRET",
   "refresh_token": "YOUR REFRESH TOKEN"} 
                   

6. Then, select Send. If everything is configured correctly, Postman will return a new access token-refresh token pair in the following format:

   {
   "access_token": "string,
   "expires_in": "expiry time of access_token in second",
   "scope": "string",
   "refresh_token": "string"
   }