SDK for Node.js

Calling outside APIs

Call a payment, SMS or email API without your app ever holding its key. The platform adds the key to each request on the way out.

Set it up once in the dashboard

  1. Secrets, then Create secret: save the provider's key, for example as payment-key. Nobody can read it back after this, not even you.
  2. Connections, then Create connection: name it (for example payments), give the provider's base URL, and choose the secret and the header it goes in (usually Authorization with Bearer before it).
  3. Optional: add limits to the connection, like only POST /charges, at most 100 calls a minute, or at most 5,000 in amounts a day. They are checked before the key is used.

Make a call

server.js
app.post("/checkout", async (req, res) => {
  const charge = await cloud.connections.call("payments", "POST /charges", {
    amount: 1849,
    currency: "sgd",
    description: "Order 1027",
  });

  if (!charge.ok) {
    // The provider said no, for example a declined card.
    return res.status(402).json({ message: "Payment failed", details: charge.data });
  }
  res.json({ paid: true, chargeId: charge.data.id });
});

call(connection, route, body) sends body as JSON. Leave the method out for a GET: cloud.connections.call("payments", "/charges/ch_123").

NameTypeWhat it is
connectionstringThe connection's name from the dashboard.
routestringA method and a path, like "POST /charges", or just a path for a GET.
bodyobject (optional)Sent as JSON. A string or Buffer is sent as it is.
options.queryobject (optional)Query string values, like { limit: 10 }.
options.headersobject (optional)Extra headers for the provider. Never Authorization: the platform adds the key.

What you get back

NameTypeWhat it is
statusnumberThe provider's HTTP status, like 201.
okbooleanTrue when the status is 200 to 299.
dataobject or stringThe provider's answer: parsed JSON, or text when it isn't JSON.
headersobjectThe provider's headers, in lower case.

When the platform refuses

These throw a SecureCloudError. With errorHandler() in your app they become a clean JSON answer on their own.

NameTypeWhat it is
NOT_FOUND404No connection with that name in your workspace.
PROXY_POLICY_DENIED403A limit on the connection refused it: the route or the amount.
PROXY_RATE_LIMITED429Too many calls through this connection; try again shortly.
SECRETS_SEALED503The vault is sealed (for example after a restart) until it is unsealed.
UPSTREAM_UNAVAILABLE502The provider couldn't be reached.
server.js
const { isSecureCloudError } = require("@secure-cloud/sdk");

try {
  await cloud.connections.call("payments", "POST /charges", order);
} catch (error) {
  if (isSecureCloudError(error) && error.code === "PROXY_POLICY_DENIED") {
    return res.status(400).json({ message: "That order is over our limit." });
  }
  throw error;
}
NextFiles →