Invoke Remote API

The invokeRemote method enables apps to integrate with remote backends from within Forge functions.

To use the invokeRemote method, you need to define a remote for your backend in the manifest.yml file.

Function signature

1
2
3
4
5
6
7
8
9
10
11
12
13
import { RequestInit, Response } from 'undici';

type InvokeRemoteOptions = {
  path: string;
};

type APIResponse = Pick<Response, 'json' | 'text' | 'arrayBuffer' | 'ok' | 'status' | 'statusText' | 'headers'>

export async function invokeRemote(
  remoteKey: string,
  options: RequestInit & InvokeRemoteOptions
): Promise<APIResponse>;

Arguments

• remoteKey: Key of the remote entry in the manifest.yml file.
• path: Must be a non-empty string (like '/'). The path that will be appended to the baseUrl of the remote.
• The rest in options are as in Undici's options.

Returns

Promise<Response>, see Undici ResponseData.

Example

Making a POST request to a remote endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { invokeRemote } from '@forge/api';

const res = await invokeRemote('my-remote-key', {
  path: `/tasks/`,
  method: 'POST',
  headers: {
    'x-header-key': 'x-header-value'
  },
  body: JSON.stringify({
    department: 'Ecosystem',
    team: 'Forge',
    description: 'Write docs'
  })
});

if (!res.ok) {
  throw new Error(`invokeRemote failed: ${res.status}`);
}

const json = await res.json();
console.log(`Created task: ${JSON.stringify(json.task)}`);

Making a GET request to a remote endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { invokeRemote } from '@forge/api';

const res = await invokeRemote('my-remote-key', {
  path: `/tasks/?team=Forge`,
  method: 'GET'
});

if (!res.ok) {
  throw new Error(`invokeRemote failed: ${res.status}`);
}

const json = await res.json();
console.log(`Tasks: ${JSON.stringify(json)}`);

Context and security

When invokeRemote is called from a backend Forge function, the Forge Invocation Token context claim will contain only context.cloudId for Jira and Confluence apps, and will be an empty object otherwise. The full module context shown on Forge Remote essentials is only provided to frontend invocations of invokeRemote.

Context should only be pulled from the FCT token in your backend function, otherwise it could be untrusted user input.

Because the context will be passed to the backend through GET params or POST body, it is possible for a frontend user to spoof these parameters and make a call directly to the backend with altered values.