ManagedAPIService

Script-engine API for reading Managed API definitions and calling them. Available in Journey Script steps, Rule script actions, Script-sourced MeData Definitions and Journey Screen HTML.

Authentication is fully handled by the SDK from the Managed API's Authentication type configured on the Orchestrator. Scripts never see credentials or tokens and never build Authorization headers themselves.

Functions

fetch

ManagedAPIService.fetch(
    name: string,
    relativeUrl: string,
    options?: FetchOptions
): Promise<FetchResponse>

Performs an HTTP request against a Managed API. The request URL is baseUrl + relativeUrl, where baseUrl comes from the Managed API definition. Authentication is applied automatically according to the definition's authentication type:

Authentication type	What the SDK does
None	Sends the request as-is.
Basic	Adds an Authorization: Basic … header from username / password.
Bearer Token	Adds Authorization: Bearer <token>.
API Key	Adds the key as a header, query parameter or cookie, per the configured location.
OAuth 2.0	Obtains an access token (opening the consent screen for the Authorization Code grant when allowed by options.prompt), caches it securely, refreshes it when it expires and retries once on 401.

Parameters:

• name: string — Programmatic name of the Managed API.
• relativeUrl: string — Path appended to the Managed API's baseUrl, e.g. "/me/top/tracks?limit=10". Absolute URLs are rejected.
• options?: FetchOptions — Request options, see below. Defaults to a GET with no headers and no body.

Returns: a Promise resolving to a FetchResponse. The Promise resolves for every HTTP status; check response.ok or response.status yourself. It rejects only when the request could not be made at all: unknown Managed API, missing auth configuration, network failure, a failed or cancelled OAuth flow, or consent being required while prompt is "NEVER". Rejections are Error objects carrying name and code, see Errors.

Consent prompt policy

options.prompt controls whether the SDK may show the OAuth 2.0 consent screen. It only matters for Managed APIs with the Authorization Code grant; every other authentication type is always silent.

prompt	Behaviour
"IF_REQUIRED" (default)	Use the cached token, refresh it if expired, show the consent screen only when neither works. Use in Journeys.
"NEVER"	Same, but instead of showing consent the Promise rejects with name === "INTERACTION_REQUIRED". Use in Rule script actions and any script that runs without the user watching.
"ALWAYS"	Discard the cached token and run the consent flow from scratch. Use for "switch account" style actions. Some providers skip the screen when the user is already signed in unless prompt=consent is set as an additional parameter on the Orchestrator.

try {
  const response = await ManagedAPIService.fetch("spotify", "/me/top/tracks?limit=5");
  if (!response.ok) {
    throw new Error("Spotify returned " + response.status);
  }
  JourneyContext.putValue("topTracks", response.body.items);
  onSuccess(true);
} catch (err) {
  onError(err);
}

Background use from a Rule script action: never open UI, skip when the user has not connected the account yet.

try {
  const response = await ManagedAPIService.fetch("youtube", "/videos?myRating=like", { prompt: "NEVER" });
  onSuccess(response.ok);
} catch (err) {
  if (err.name === "INTERACTION_REQUIRED") {
    console.log("YouTube not connected yet, skipping");
    onSuccess(true);
    return;
  }
  onError(err);
}

Sending a body:

const response = await ManagedAPIService.fetch("crm", "/contacts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ada" }),
});

getManagedAPIs

ManagedAPIService.getManagedAPIs(): Promise<DataMap[]>

Retrieves the key-value pairs of all Managed APIs stored on the device.

Parameters: None.

getManagedAPI

ManagedAPIService.getManagedAPI(
    name: string
): Promise<DataMap | null>

Retrieves the key-value pairs of a single Managed API by its programmatic name. Authentication settings are not included.

Parameters:

• name: string — Programmatic name of the Managed API.

Classes

FetchOptions

{
  method?: string,                    // HTTP method, defaults to "GET"
  headers?: { [key: string]: string },// request headers; no defaults are added
  body?: string,                      // must be a string; objects are not serialized
  prompt?: "IF_REQUIRED" | "NEVER" | "ALWAYS" // OAuth 2.0 consent policy, defaults to "IF_REQUIRED"
}

Set Content-Type yourself when sending a body. JSON.stringify the body yourself.

FetchResponse

{
  status: number,                     // HTTP status code
  ok: boolean,                        // true for 2xx
  headers: { [key: string]: string }, // response headers
  body: any                           // parsed JSON when the body is JSON, otherwise a string; null when empty
}

DataMap

{ [key: string]: string }

Errors

Every rejection from ManagedAPIService is an Error with two extra fields:

{
  name: string,    // stable identifier, e.g. "INTERACTION_REQUIRED", "NOT_FOUND", "API_ERROR"
  code: number,    // numeric SDK error code, e.g. 1019
  message: string  // human readable detail
}

name	code	When
INTERACTION_REQUIRED	1019	Consent is needed but prompt is "NEVER", or no screen is available to show it.
NOT_FOUND	1004	No Managed API with that name on the device.
MISSING_PARAMS	1016	The Managed API's authentication settings are incomplete.
INVALID_DATA	1008	Bad relativeUrl, baseUrl or auth setting value.
API_ERROR	1002	Network failure or a failed OAuth token request.
JOURNEY_EXECUTION_ERROR	1018	The consent screen was cancelled by the user or failed to open.
GENERAL_ERROR	1000	Anything else.

Compare on err.name; it is stable across SDK versions and platforms.