requestRemote

The requestRemote bridge method allows Forge apps to make direct requests to remote backends from UI Kit and Custom UI applications. This method is optimized for latency-sensitive requests that affect user experience and don't require OAuth tokens. The method returns a standard WHATWG fetch Response object.

Unlike invokeRemote, requests made with requestRemote are not treated as official invocations and are not proxied through the Forge platform. This means requestRemote will not include OAuth tokens, even if configured for the remote, and will not be reflected in invocation metrics in the Developer console.

Similar to invokeRemote, requests include a Forge Invocation Token (FIT) as a bearer token in the authorization header. The FIT is a JWT that contains key information about the invocation context, signed into the claims.

You may choose to use requestRemote over invokeRemote for latency sensitive applications, which directly impacts user experience and you don't need OAuth tokens for Atlassian API calls.

Function signature

1
2
type RequestRemoteOptions = {
  path: string;
};

function requestRemote(
  remoteKey: string,
  options?: RequestRemoteOptions & RequestInit,
): Promise<Response>

Arguments

• remoteKey: Key of the remote entry in the manifest.yml file.
• options:
  • path: URL path appended to the remote's baseUrl. Example: if baseUrl is https://api.example.com and path is /users/123, the final URL becomes https://api.example.com/users/123
  • Supports all standard RequestInit properties like method, headers and body, but does not not support signal

Returns

• A Promise that resolves with a WHATWG fetch Response object.

Example

Making a POST request to a remote endpoint:

1
2
import { requestRemote } from '@forge/bridge';

const response = await requestRemote('my-remote-key', {
  path: `/tasks/?team=Forge`,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'custom-header': 'custome-value'
  },
  body: JSON.stringify({
    taskName: 'My cool Forge task'
  })
});

if (!response.ok) {
  throw new Error(`request failed with the following status code: ${response.status}`);
}

Making a GET request to a remote endpoint

1
2
import { requestRemote } from '@forge/bridge';

const response = await requestRemote('my-remote-key', {
  path: `/tasks/?team=Forge`,
  method: 'GET',
  headers: {
    'custom-header': 'custome-value'
  },
});

if (!response.ok) {
  throw new Error(`request failed with the following status code: ${response.status}`);
}

Limitations

• FormData: Sending FormData is currently not supported. Please follow the Forge changelog for updates.
• FIT claims: The FIT sent in the authorization header does not include the principal and app.license fields in the claims. We intend to add these, please follow the Forge changelog for updates.
• Streaming: Response body streaming is not supported. The entire response must be received before processing.
• OAuth tokens: Unlike invokeRemote, OAuth tokens are not included in requests. If you require them to be delievered on invocation, please use invokeRemote instead.
• Metrics: Requests are not tracked in the Developer Console's invocation metrics.
• FIT refresh: FIT tokens are cached but may expire. The API handles renewal automatically, but be prepared for occasional additional latency on the first request and longer user sessions.