Async events API
Fetch API
Storage API

Rate this page:

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}`;

You have the option to bypass this requirement by using assumeTrustedRoute from @forge/api. However, you should only do this if absolutely needed because this puts you at risk of security vulnerabilities if used without a validated or trusted route.

Contextual methods

Interface

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

Methods

MethodDescription
api.asApp()Use this method to call an Atlassian API as the app, using the app user. If your app has all the required permissions, the request will work regardless of who uses the app.
api.asUser()

Use this method to call an Atlassian API as the user of the app.

If the user initiating the request has not granted permission to the app, the request is made without a valid Authorization header.

If the API returns a 401 and there isn't a valid Authorization header, then an Error is thrown.

  • If this error isn't caught, the user is prompted to grant access to the app.
  • If the user grants access, the app is re-initialized.

Note: This context method is only available in modules that support the UI kit.

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

NameTypeDescription
querystring

The GraphQL query or mutation.

variablesobject

Variables to be used in the GraphQL query.

headersobject

HTTP headers to be included in the request.

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.

Rate this page: