Last updated Apr 25, 2024

Calling product APIs from a remote

Once your remote backend has received a request from Forge, you can call product APIs.

Prerequisites

When setting up your app to:

Call a remote (from a Custom UI or UI Kit 2 frontend)
Send product and lifecycle events (to a remote)
Configure scheduled triggers to invoke a remote backend

You’ll need one of the following in your manifest.yml:

endpoint.auth.appSystemToken set to true
endpoint.auth.appUserToken set to true

Which one you need depends on whether you want to access product APIs as a generic bot user (appSystemToken) or the current user’s permission (appUserToken).

This ensures requests to your remote contain an x-forge-oauth-system or x-forge-oauth-user header, containing a token you can use to call product and Forge storage APIs.

Token Expiry

Both of these tokens are encoded in JWT. The exp claim in their payload represents the expiration time.

We recommend adding a lifecycle events trigger for the installation and upgrade events to ensure that your app starts off with a token available.
If your app needs to ensure the access token is periodically refreshed, consider utilizing a scheduled trigger. There is no endpoint for proactively refreshing the access token.
As there is no lifecycle event sent upon app uninstallation yet (FRGE-1246), product APIs returning 4xx can indicate the app is no longer installed on the tenant. You can infer the app was uninstalled if it stopped receiving a scheduled trigger.

Getting started

Once you’ve got your token, you can use it in backend requests to Product APIs.

Node.js example

This example uses the fetch function from the node-fetch module to request data from the Confluence API:

1
2
'use strict'
import fetch from 'node-fetch';

export async function fetchFromConfluence(token, apiBaseUrl) {
  const headers = {
    Accept: 'application/json',
    Authorization: `Bearer ${token}`
  }
  return await fetch(`${apiBaseUrl}/wiki/rest/api/content`, { headers });
}

For more detail, see the Confluence node client in Bitbucket.

For Connect apps that have adopted Forge, the Atlassian Connect Express framework provides a method getForgeAppToken to retrieve an app token stored in a request from the Forge platform.

Java example

This example uses a GET request to call from a Confluence Content API:

1
2
public ResponseEntity<String> getContent(final String token, String baseUrl) {

    final HttpHeaders headers = new HttpHeaders();
    headers.setBearerAuth(token);

    final HttpEntity<String> entity = new HttpEntity<>(null, headers);

    final ResponseEntity<String> response =
            restTemplate.exchange(baseUrl + "/wiki/rest/api/content",
                    HttpMethod.GET, entity, String.class);

    logger.info("Response statusCode={}", response.getStatusCode());

    return response;
}

For more detail, see the Confluence java client in Bitbucket.

For Connect apps that have adopted Forge, the Atlassian Connect Spring Boot framework provides a method asApp(String installationId) to send a request using a stored app access token. An example is available at Forge Remote Sample.

Product APIs

For a complete list of each of the product APIs that you can call from your remote:

Next steps

For further help, see how you can: