Display conditions
Permissions

Forge remote capabilities are now in preview.

Where indicated, some content in this topic applies only to these preview capabilities.

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

Endpoint

When specifying a remote resolver that implements custom functionality for a Forge module, the endpoint that the app communicates with is listed in the remotes section of the manifest.yml file, and is referenced by key.

An endpoint property of the resolver object specifies the key of the endpoint entry to use as the resolver.

PropertyTypeRequiredDescription
keystringYes

A key for the endpoint, which other modules can refer to. Must be unique within the list of endpoints and have a maximum of 23 characters.

Regex: ^[a-zA-Z0-9_-]+$

remotestringYesThe remote key that defines the base portion of the path for this endpoint.
route{path:string}No

The path appended to the baseUrl property of the remote object when invoking this endpoint.

This property is only required for backend module endpoints.

UI module remote resolver endpoint paths are always specified in invokeRemote requests in the app's front end.

authobjectNoAn object that defines the auth options available to the remote endpoint when calling Forge functions
auth.appUserToken.enabledbooleanNo

If true and the remote endpoint is invoked within a user's login session, Forge includes an appUserToken in the Forge Invocation Token it sends to the remote app.

This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the user in whose login session the app is running.

Specifically, the API will have only as much access to the site's data as that user does. For example, if the user does not have permission to see pages in a particular space or issues in a particular project, the API won't provide them access to that space or page, either.

Forge modules that run outside of a user's login session, such as an app lifecycle event or product event are not associated with a user and cannot send an appUserToken to the remote app.

If an endpoint opts to enable remote user token access, the read:appUserToken scope must also be specified in the Permissions section of the manifest.

auth.appSystemToken.enabledbooleanNo

If true, Forge includes an appSystemToken in the Forge Invocation Token it sends to the remote app.

This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the generic "bot user for the app.

If an endpoint opts to enable remote system token access, the read:appSystemToken scope must also be specified in the Permissions section of the manifest.

Modifying the endpoint entries results in a major version upgrade of your app upon deploy. Your app users will again be required to consent to your app's permissions.

Example

1
2
endpoint:
  - key: remote-hello-world-ui
    remote: remote-app
    route:
      path: echo/
    auth:
      appUserToken:
        enabled: true
      appSystemToken:
        enabled: false

Rate this page: