Calling Atlassian app APIs from a remote

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

Prerequisites

When setting up your app to:

• Call a remote (from a Custom UI or UI Kit 2 frontend)
• Send Atlassian app 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 Atlassian app 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 Atlassian app 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), Atlassian app 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 Atlassian app APIs.

Getting the API Base URL

The apiBaseUrl is provided in the FIT token under the app.apiBaseUrl claim. This is the base URL where all Atlassian app API requests should be routed.

To use it:

1. Parse the FIT token (received in the Authorization header of requests to your remote)
2. Extract the app.apiBaseUrl field from the token's claims
3. Use this value as the base URL when calling Atlassian app APIs

Example FIT token claim:

1
2
{
  "app": {
    "apiBaseUrl": "https://api.atlassian.com/ex/confluence/4c822e2f-510f-48b9-b8d0-8419d0932949",
    "installationId": "ari:cloud:ecosystem::installation/...",
    "id": "ari:cloud:ecosystem::app/..."
  }
}

Important: The apiBaseUrl is NOT the same as your site URL (e.g., yoursite.atlassian.net). Always use the apiBaseUrl from the FIT token.

For details on the FIT token structure and validation, see Forge Invocation Token (FIT).

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 the Confluence Content API:

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

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

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

    final ResponseEntity<String> response =
            restTemplate.exchange(apiBaseUrl + "/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.

Offline user impersonation

Apps have the ability to impersonate any user in their installation context, subject to a number of conditions. For more information, see:

• How to declare scopes for offline impersonation
• Restrictions for offline user impersonation

On a Forge remote, impersonating a user that's not in session requires exchanging the app system token for an authorisation token for another user. This can be done by calling a special mutation on Atlassian's GraphQL Gateway. This mutation is configured to allow being called from a Forge remote using a Forge app system token.

1
2
mutation forge_remote_offlineUserAuthToken($input: OfflineUserAuthTokenInput!) {
  offlineUserAuthToken(input: $input) {
    success
    errors {
      message
    }
    authToken {
      token
      ttl
    }
  }
}

Where input contains:

1
2
{
  contextIds: ["<context ARI of the installation>"],
  userId: "<account ID being impersonated>"
}

This can be called by calling the GraphQL gateway at https://api.atlassian.com/graphql and setting the Authorization header to Bearer ${appSystemToken}. If success is set to true in the response, the corresponding token in authToken can be used in the same way as the app system token or app user token in the examples above. This will make API calls authenticated as the given account ID, subject to the constraints of offline user impersonation.

The ttl is the token lifetime in seconds. This can be used to cache a particular user token for a given installation and user ID, we recommend doing this if your app will make multiple impersonation calls for the same user.

The rate limit for requesting user impersonation tokens using this mutation is 10,000 requests per minute, per app.

Node.js example

1
2
const query = "<as above>";

async getTokenForUser(systemToken, contextAri, userAccountId) {
  const response = await fetch("https://api.atlassian.com/graphql", {
    method: "POST",
    headers: {
      accept: "application/json",
      "content-type": "application/json",
      authorization: `Bearer ${systemToken}`,
    },
    body: JSON.stringify({
      query,
      variables: {
        input: {
          contextIds: [contextAri],
          userId: userAccountId,
        },
      },
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  const json = await response.json();

  if (!json.data.offlineUserAuthToken.success) {
    throw new Error(`GraphQL error: ${json.data.offlineUserAuthToken.errors}`);
  }

  // returns { token: "<token>", ttl: <token TTL> }
  return json.data.offlineUserAuthToken.authToken;
}

Atlassian app APIs

For a complete list of Atlassian app APIs that you can call from your remote, see :

• Jira REST APIs
• Jira Service Management REST APIs
• Confluence REST APIs
• Compass GraphQL toolkit
• Bitbucket REST APIs

Next steps

For further help, see how you can:

• Access Forge storage (from your remote)
• Perform Bitbucket git operations (from your remote)
• View the working reference app code
• Learn how to observe error metrics, logs, and tracing