Product authentication

The product fetch API enables you to make requests to Atlassian product APIs from within your Forge app. The client includes an Authorization header based on the context-bound fetch call.

Import the Forge API package in your app, as follows:

1
2
import api, { route } from '@forge/api';

To check the status of a request, use status as shown below:

1
2
const result = await api
    .asApp()
    .[requestConfluence | requestJira](
      route`/rest/api/`
    );
const status = result.status;

route

You must use the route tagged template function to construct the path that's passed to the product fetch APIs. route is a tagged template function that runs encodeURIComponent on each interpolated parameter in the template string. This provides protection against security vulnerabilities, such as path traversal and query string injection.

Usage

1
2
import { route } from '@forge/api';

// With no parameters
route`/rest/api/3/myself`;

// With parameter: e.g. '/rest/api/3/issue/ISSUE-1'
route`/rest/api/3/issue/${issueKey}`;

// With query parameters: e.g. '/rest/api/3/issue/ISSUE-1?fields=summary'
route`/rest/api/3/issue/${issueKey}?fields=${fieldsToDisplay}`;

// With more complex query parameters: e.g. '/rest/api/3/issue/ISSUE-1?fields=summary' or '/rest/api/3/issue/ISSUE-1'
const queryParams = new URLSearchParams({
  ...(filterFields ? { fields: fieldsToDisplay } : {}),
});
route`/rest/api/3/issue/${issueKey}?${queryParams}`;

Contextual methods

Interface

1
2
api.[contextMethod](): <{
  requestConfluence,
  requestJira,
}>

Methods

requestConfluence

Makes a request to the Confluence REST API.

Method signature

1
2
// Authenticated
api.[asApp | asUser]().requestConfluence(path[, options]) => Promise<Response>

// Unauthenticated (used for operations that do not support OAuth 2.0)
api.requestConfluence(path[, options]) => Promise<Response>

Parameters

Authenticated example

Make a request to the /wiki/rest/api/content resource on the Confluence site where the app is installed:

1
2
api.[asApp | asUser]().requestConfluence(route`/wiki/rest/api/content`);

Unauthenticated example

Make a request to the /wiki/rest/api/audit resource on the Confluence site where the app is installed, using basic authentication:

1
2
api.requestConfluence(route`/wiki/rest/api/audit`, {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});

requestJira

Makes a request to the Jira REST API.

Method signature

1
2
// Authenticated
api.[asApp | asUser]().requestJira(path[, options]) => Promise<Response>

// Unauthenticated (used for operations that do not support OAuth 2.0)
api.requestJira(path[, options]) => Promise<Response>

Parameters

Authenticated example

Make a request to the /rest/api/3/myself resource on the Jira site where the app is installed:

1
2
api.[asApp | asUser]().requestJira(route`/rest/api/3/myself`);

By default, the request method type is GET. To send another request type, use the options object. This example shows setting the method to POST to add a watcher to an issue:

1
2
api.[asApp | asUser]()
    .requestJira(route`/rest/api/3/issue/${issueKey}/watchers`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify(`${accountId}`)
    });

Unauthenticated example

Make a request to the /rest/api/2/auditing/record resource on the Jira site where the app is installed, using basic authentication:

1
2
api.requestJira(route`/rest/api/2/auditing/record`, {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});

requestGraph

Makes a request to the Atlassian platform GraphQL API, for Atlassian products that expose GraphQL API endpoints. For example, you can make Compass requests using requestGraph. Compass requests need to include the X-ExperimentalApi: compass-beta header.

Compass Forge apps can use the GraphQL API Toolkit to execute pre-written queries, as an alternative to the requestGraph method.

Method signature

1
2
// Only authenticated calls are permitted
api.[asApp | asUser]().requestGraph(query, variables, headers) => Promise<Response>

Parameters

Authenticated example

Fetch the name of the current user:

1
2
import api from '@forge/api';
import ForgeUI, { useEffect, useState } from '@forge/ui';

const [result, setResult] = useState(null);
const query = "query { me { user { name } } }";
const variables = { "key1": "value1", "key2": "value2" };
const headers = { "key1": "value1", "key2": "value2" };

useEffect(async () => {
  const request = await api.asApp().requestGraph(query, variables, headers);
  setResult(request.json());
}, []);

if(result) {
    console.log(result.data ? result.data.me.user.name : "No data");
    console.log(result.errors ? result.errors : "No errors");
};

Successful queries return their result in the data object. Any errors are returned as an array in the errors object.