secrets

A script that calls a paid API needs a key. Pasting it into the code leaves it in the canvas for everyone and every copy to see. The org vault keeps it elsewhere: the code writes a placeholder, and ixi swaps in the real value on the way out.

add a secret

Open Organization from your user menu and choose the Secrets tab (/org?tab=secrets). Under Sandbox secrets:

1. Type a name in the left field. Names are UPPER_SNAKE: capital letters, digits and underscores, starting with a letter, up to 64 characters. Lowercase is capitalised for you. The field shows OPENWEATHER_KEY as an example.
2. Paste the key into secret value.
3. Press Save.

The list shows names, the date and ••••••••. Values can't be read back, not by you, not by an admin and not by a pixie. Saving an existing name replaces the value, which is how you rotate a key. The bin deletes one.

Only org owners and admins can add, rotate or delete secrets. Any member can see the names.

use it in a script

Write the placeholder $IXI_SECRET:NAME wherever the key belongs in a request's address or headers:

export default async (inputs) => {
  const r = await fetch('https://api.openweathermap.org/data/2.5/weather?q=' + inputs.city, {
    headers: { 'x-api-key': '$IXI_SECRET:OPENWEATHER_KEY' },
  });
  return r.json();
};

The script runs in the cloud, and the placeholder is replaced as the request leaves. The code never sees the key, so it cannot print it, return it or store it in a result.

The sandbox must also declare the names it uses. The declaration is part of the node, and a run can only use names the node already lists: a caller cannot ask for a different vault key. Ask the sandbox's dev pixie to add the secret, for example use the OPENWEATHER_KEY secret, and it declares the name.

lock a secret to its host

Each secret can be locked to the hosts it may be sent to. Ask the pixie: only send OPENWEATHER_KEY to api.openweathermap.org. The node stores a list per secret, and ixi then substitutes that secret only on requests to those hosts. An entry matches the host itself or any subdomain of it.

Without a lock, a secret works on any public host. So lock every key that matters: a script that is allowed to use a key still cannot be talked into sending it to a stranger's server.

Two more guards apply on every request:

• A request is checked before any secret goes in, and a placeholder on a request to another host stays a placeholder.
• Redirects are never followed with a secret attached; the redirect comes back to the script, and a new request to the next host gets its own check.

who can run it

A run that uses secrets is stricter than other runs. The person (or the pixie acting for them) must be:

• a member of the org that owns the canvas, and
• allowed to write to the canvas.

Someone viewing a public or shared-by-link canvas can read the result already on it but cannot start a run that spends a key.

limits & good to know

• Secrets are available to script sandboxes, which run in the cloud. A frame in your browser has no way to reach the vault.
• A script run has 30 seconds and 32 outgoing requests; requests to private addresses are blocked.

related

• scripts and cloud runs — how a script runs.
• secrets and API keys — the org-level view of the vault.
• members and roles — who counts as an admin.