Browse documentation

Keys

Declare a key

Declares a key on this agent. Its value goes to encrypted storage and is never returned. A refusal names the field in param; a name the agent already has, as a key or a variable, is refused with 409. A key's exact hosts join the agent's allowed hosts for every Turn that holds its badge, so declaring one requires agents:write as well as env_vars:write; without either it is refused with 403.

POST/agents/{agentId}/keys

Authorization

AuthorizationBearer <token>

Path parameters

agentIdstringrequired

format: "uuid"

Headers

Salambo-Clientstring

Which published Salambo client sent the request, as cli/<version> or sdk/<version>. The CLI and SDK send it on every request; a request without it, or with a value in another shape, is served as usual. The API refuses a CLI below its minimum supported version with 426.

maxLength: 100

Bodyrequired

application/json

union

A fixed key takes value. Traded (refreshToken, optional clientSecret) and signed (privateKey) keys take a recipe and are refused while key renewal is not available. Hosts are public hostnames: no IP address, port or path, no private name (localhost, .local, .internal, .arpa); a wildcard only as *.example.com. A wildcard host never joins the agent's allowed hosts: it is reachable only where the agent's own list covers it.

All of these rules apply

object1

object

namestringrequired

pattern: "^[A-Z][A-Z0-9_]*$"
maxLength: 100

allowedHostsarrayrequired

minItems: 1
maxItems: 20

Show nested schema

Array items

string

forGitboolean

Git uses the key on each of its hosts but the wildcards.

default: false

object2

object

kindstringrequired

enum: ["fixed","traded","signed"]

valuestring

minLength: 1
writeOnly: true

refreshTokenstring

minLength: 1
writeOnly: true

clientSecretstring

minLength: 1
writeOnly: true

privateKeystring

minLength: 1
writeOnly: true

recipeobject

How the broker trades or signs the key: token URL (HTTPS, public), form fields, headers, JWT claims and response mapping. Holds no secret; a field points at the key's value with { "from": "refresh_token" }.

Additional properties are allowed.

Response

application/json

The declared key, without its value

object

idstringrequired

format: "uuid"

objectstringrequired

const: "agent_key"

namestringrequired

kindstringrequired

enum: ["fixed","traded","signed"]

allowed_hostsarrayrequired

Show nested schema

Array items

string

git_scopesarrayrequired

The hosts, and optionally repository owners, git uses this key for.

Show nested schema

Array items

object

hoststringrequired

ownerstring | nullrequired

statusstringrequired

enum: ["active","needs_new_token"]

value_updated_atintegerrequired

last_used_atinteger | nullrequired

created_atintegerrequired

updated_atintegerrequired

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/agents/{agentId}/keys' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '@request.json'

Replace placeholders before running. JSON templates without a sample body read your payload from request.json.

Response

{
  "id": "<string>",
  "object": "agent_key",
  "name": "<string>",
  "kind": "fixed",
  "allowed_hosts": [
    "<string>"
  ],
  "git_scopes": [
    {
      "host": "<string>",
      "owner": "<string | null>"
    }
  ],
  "status": "active",
  "value_updated_at": 123,
  "last_used_at": 123,
  "created_at": 123,
  "updated_at": 123
}