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
- Secrets, then Create secret: save the provider's key, for example as
payment-key. Nobody can read it back after this, not even you. - 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 (usuallyAuthorizationwithBearerbefore it). - 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
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").
| Name | Type | What it is |
|---|---|---|
connection | string | The connection's name from the dashboard. |
route | string | A method and a path, like "POST /charges", or just a path for a GET. |
body | object (optional) | Sent as JSON. A string or Buffer is sent as it is. |
options.query | object (optional) | Query string values, like { limit: 10 }. |
options.headers | object (optional) | Extra headers for the provider. Never Authorization: the platform adds the key. |
What you get back
| Name | Type | What it is |
|---|---|---|
status | number | The provider's HTTP status, like 201. |
ok | boolean | True when the status is 200 to 299. |
data | object or string | The provider's answer: parsed JSON, or text when it isn't JSON. |
headers | object | The 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.
| Name | Type | What it is |
|---|---|---|
NOT_FOUND | 404 | No connection with that name in your workspace. |
PROXY_POLICY_DENIED | 403 | A limit on the connection refused it: the route or the amount. |
PROXY_RATE_LIMITED | 429 | Too many calls through this connection; try again shortly. |
SECRETS_SEALED | 503 | The vault is sealed (for example after a restart) until it is unsealed. |
UPSTREAM_UNAVAILABLE | 502 | The provider couldn't be reached. |
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;
}