Forge Remote essentials

There are some key considerations and responsibilities when using Forge Remote.

• Increased responsibility
• Remote contract
• Verifying remote requests
• Data residency eligibility
• Reference materials

Remote contract

This section defines the contract used by remote requests including HTTPS protocol level details, request and response schema.

Method usage

When using invokeRemote in your Forge app's frontend or backend, you specify the method and path for the endpoint in the invokeRemote call.

When using Forge Remote with events or a scheduled trigger, the request is automatically routed to the endpoint configured in the manifest using the POST method.

IP address ranges used when invoking remote backends from Forge

When communicating with remote backends, Forge uses IP address ranges as indicated in the Outgoing Connections section of IP addresses and domains for Atlassian cloud apps. This information may be important if your app's remote backend is behind a firewall or other network equipment that restricts access based on IP address.

Request headers

The following headers are added to requests to your remote.

As an example:

1
2
x-b3-traceid: a523b7549f0b88c9
x-b3-spanid: 2a2436c64727923f
authorization: Bearer ${FIT}
x-forge-oauth-system: ${OAuth-System-Token}
x-forge-oauth-user: ${OAuth-User-Token}
header1: value ## Set customer headers when invoking your remote from a UI module

Errors

Requests that exceed the timeout or do not return a 2xx HTTP Status Code, will be considered as a failure and will appear in the developer console metrics. See Remote observability for more on metrics and logging.

The Forge Invocation Token (FIT)

Requests to your remote backend will include a Forge Invocation Token (FIT) as a bearer token in the authorization header. The FIT includes important information about the invocation context and should be used to verify that the request came from Atlassian and is intended for your app.

The Forge Invocation Token contains a JSON object with the following properties:

Example:

1
2
{
  "app": {
    "id": "ari:cloud:ecosystem::app/8db33809-1f32-48bb-8c52-5877dab48107",
    "version": "16",
    "appVersion": "16.0.1",
    "installationId": "ari:cloud:ecosystem::installation/0a3a7799-53ae-4a5b-9e7e-03338980abb5",
    "apiBaseUrl": "https://api.stg.atlassian.com/ex/confluence/d0d52620-3203-4cfa-8db5-f2587155f0dd",
    "environment": {
      "type": "DEVELOPMENT",
      "id": "ari:cloud:ecosystem::environment/8db33809-1f32-48bb-8c52-5877dab48107/aa911f10-c54b-4b93-9e27-dd2947840b9e"
    },
    "module": {
      "type": "xen:macro",
      "key": "forge-remote-app-boot"
    },
    "license": {
      "active": true,
      "billingPeriod": "MONTHLY",
      "capabilitySet": "capabilityAdvanced",
      "ccpEntitlementId": "5e176cc2-6fa0-3c7b-8fc4-302443a16e86",
      "ccpEntitlementSlug": "X-3SH-1A6-33A-AS0",
      "isEvaluation": false,
      "subscriptionEndDate": "2026-12-08T00:00:00.000Z",
      "supportEntitlementNumber": null,
      "trialEndDate": "1989949707000",
      "type": "commercial",
      "modes": ["USER_ACCESS"]
    }
  },
  "context": {
    "localId": "4654fa12-4c7c-4792-95a9-6019edb27953",
    "cloudId": "d0d52620-3203-4cfa-8db5-f2587155f0dd",
    "moduleKey": "forge-remote-app-boot",
    "siteUrl": "https://pbray2.jira-dev.com",
    "extension": {
      "type": "macro",
      "content": {
        "id": "5341185"
      },
      "space": {
        "key": "~655362312d3308895442b0aa38771a10c88656",
        "id": "65538"
      },
      "isEditing": false,
      "references": []
    }
  },
  "principal": "655362:312d3308-8954-42b0-aa38-771a10c88656",
  "aud": "ari:cloud:ecosystem::app/8db33809-1f32-48bb-8c52-5877dab48107",
  "iss": "forge/invocation-token",
  "iat": 1700175149,
  "nbf": 1700175149,
  "exp": 1700175174,
  "jti": "d8a496253ec8c18a54631e4c82cbedd5d0ae8570"
}

Verifying remote requests

If you implement a remote backend, you take on additional responsibilities under the Forge Shared responsibility model.

You must ensure that you:

• Validate all JWT Forge Invocation Tokens provided to your remote endpoint in an authorization header against the following JWKS to ensure that they originated from Atlassian Forge and were intended for an audience of your Application ID.
• Never share or log any OAuth access tokens provided.

To help illustrate the requirements for the above, here is some sample code in both Javascript and Java, which is available from the linked repos.

Example code in Java:

1
2
@Component
public class FITValidator {

    @Value("${jwks.endpoint:https://forge.cdn.prod.atlassian-dev.net/.well-known/jwks.json}")
    private String jwksUrl;

    @Value("${appId}")
    private String appId;

    public void validate(String invocationToken) throws InvalidJwtException {
        var httpsJwks = new HttpsJwks(jwksUrl);
        var httpsJwksKeyResolver = new HttpsJwksVerificationKeyResolver(httpsJwks);
        var jwtConsumer = new JwtConsumerBuilder()
                .setVerificationKeyResolver(httpsJwksKeyResolver)
                .setExpectedAudience(appId)
                .setExpectedIssuer("forge/invocation-token")
                .build();

        jwtConsumer.process(invocationToken);
    }
}

Example code in Javascript:

1
2
export const validateContextToken = async (invocationToken, appId) => {
  const jwksUrl = 'https://forge.cdn.prod.atlassian-dev.net/.well-known/jwks.json';
  const JWKS = jose.createRemoteJWKSet(new URL(jwksUrl));

  const payload = await jose.jwtVerify(invocationToken, JWKS, {audience: appId});
  return payload;
}

Data residency eligibility

When an app contains a remotes declaration, Forge will (by default) assume the app is storing in-scope end-user data on a remote backend.

To qualify for the PINNED status, you must explicitly declare that your remote backend does not store in-scope End-User Data. Alternatively, apps can still achieve PINNED status if they store in-scope End-User Data on a remote backend configured with region-specific URLs. To meet data residency requirements, update the manifest file by defining region-specific baseUrl values and marking them with inScopeEUD: true to ensure compliance with data residency standards. See Remotes for specific instructions on how to do this in your manifest.

Best practice for storing data passed to a Forge Remote

We strongly advise to store data against installationId because it is guaranteed to always be available for all apps, and other identifiers may not be available in the future. If you are using cloudId (for Jira and Confluence apps) or workspaceId (for Bitbucket apps), do so with caution and monitor the Forge Changelog in case identifiers change.

Migrating from Connect to Forge

During migration, you’ll often need to cross-reference stored data between your Connect and Forge apps. Because installationId only applies to Forge apps, and most Connect apps store data against clientKey, Forge has temporarily made clientKey available in Forge until Connect reaches end-of-support. For more details, see the changelog announcement and the migration guide at Retrieving the Connect clientKey in Forge.

Recovering data if installationId changes

If you reinstall an app the installationId will change. Reinstallation occurs either directly (when running forge install followed by forge uninstall) or through recovery operations that involve site recreation or whole product imports.

App upgrades (minor or major) do not change the value of installationId.

Because of this, we are aware that storing data against installationId isn’t ideal and does require manual intervention when the value changes.

Recovering data stored remotely

For data stored in your own data store, you must manually map the old installationId to the new installationId. You can find the new installationId in the FIT token claims of recent invocations as you did before or by contacting Atlassian support.

Recovering data stored using Forge Storage

If you are using Forge Storage, you must contact Atlassian support who can link the new installation to the old data, within a retention period. See Hosted storage data lifecycle - App reinstallation.

Reference materials

Forge Remote makes particular use of some manifest.yml sections and properties, runtime APIs, and data structures you might not have encountered before.