Templates ›

Set template variable hosts

PUT/v1/templates/{id}/secrets/variables/{name}/hosts

Narrows the hosts one of the template's kept-out variables is sent to, without sending its value again: each host has to be one it is sent to now, or under one of its wildcards. Its value and its stand-in stay as they are. A host it is not sent to now is refused with hosts_widened, since only someone who has the value may send it somewhere new: set it again with its value and hosts. A plain variable is refused with not_hidden: to keep one out, set it with its value and hosts. A sandbox on the template takes the change when it next starts, or when POST /v1/templates/{id}/apply names it.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const template = await agental.templates.get("tpl_0123456789abcdef");
await template.secrets.setHosts("GITHUB_TOKEN", ["api.github.com"]);

Answer200 OK · HiddenVariable

{
"name": string,
"hidden": "true",
"hosts": string[],
"standIn": string,
}

The variable as it is kept, with its hosts from now on.

Path

`id`required string	e.g. `"tpl_0123456789abcdef"`
`name`required string	e.g. `"DATABASE_URL"`

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

hostsrequired

array of string

1 to 10 hosts its value may be sent to, over HTTPS: hostnames, as api.github.com, and wildcards, as *.example.com, which cover every name under example.com and not example.com itself. Lowercase, with no scheme, port, path or address. A name on the Public Suffix List, private section included, is refused, and so is a wildcard directly over one: *.com, *.co.uk, *.github.io. e.g. ["api.github.com","github.com"]

Returns

200 The variable as it is kept, with its hosts from now on.

HiddenVariable4 fields

name

string

hidden

true

It is kept out of the sandbox: its commands see standIn, and the proxy on the sandbox's server puts the value in place of the stand-in on HTTPS requests to its hosts.

Its value is never given back, to its owner or anyone.

hosts

string[]

Where its value may be sent: hostnames, and wildcards as *.example.com, which cover every name under example.com and not example.com itself.

standIn

string

What its commands see in its place.

It stays the same when the value is replaced, so a file that holds it keeps working, and it is the same in every sandbox on a template. Sent anywhere but its hosts it is worth nothing.

Errors and other answers

400	`invalid_request` the name or value is not one that can be kept.
400	`invalid_host` a host cannot be one, or there are none or more than 10, and the message says which and why.
404	Not found.
409	`not_hidden` the variable is plain: its commands read its value.
409	`hosts_widened` a host is not among those it is sent to now, and sending it somewhere new needs its value. Nothing was changed.
501	`hidden_variables_unavailable` hosts were sent where GET /v1/policy says hiddenVariables is false. Nothing was changed.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Delete template variable Get template files →