Create a tool set secret

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const toolSetSecret = await client.toolSets.secrets.create('toolset_01HXKD2E5NQM3T9AYWCFNRMN74', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  metadata: { name: 'name' },
  spec: {},
});

console.log(toolSetSecret.metadata);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
tool_set_secret = client.tool_sets.secrets.create(
    tool_set_id="toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    metadata={
        "name": "name"
    },
    spec={},
)
print(tool_set_secret.metadata)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
	"go.cadenya.com/cadenya-go/shared"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	toolSetSecret, err := client.ToolSets.Secrets.New(
		context.TODO(),
		"toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
		cadenya.ToolSetSecretNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Metadata: shared.CreateResourceMetadataParam{
				Name: "name",
			},
			Spec: cadenya.ToolSetSecretSpecParam{},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", toolSetSecret.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

tool_set_secret = cadenya.tool_sets.secrets.create(
  "toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  metadata: {name: "name"},
  spec: {}
)

puts(tool_set_secret)

cadenya tool-sets:secrets create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --tool-set-id toolset_01HXKD2E5NQM3T9AYWCFNRMN74 \
  --metadata '{name: name}' \
  --spec '{}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "<string>",
    "externalId": "<string>",
    "labels": {}
  },
  "spec": {
    "value": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'name' => '<string>',
        'externalId' => '<string>',
        'labels' => [
                
        ]
    ],
    'spec' => [
        'value' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"labels\": {}\n  },\n  \"spec\": {\n    \"value\": \"<string>\"\n  }\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "labels": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "value": "<string>"
  },
  "info": {
    "lastUsedAt": "2023-11-07T05:31:56Z",
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

workspaces

{workspaceId}

tool_sets

{toolSetId}

secrets

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const toolSetSecret = await client.toolSets.secrets.create('toolset_01HXKD2E5NQM3T9AYWCFNRMN74', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  metadata: { name: 'name' },
  spec: {},
});

console.log(toolSetSecret.metadata);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
tool_set_secret = client.tool_sets.secrets.create(
    tool_set_id="toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    metadata={
        "name": "name"
    },
    spec={},
)
print(tool_set_secret.metadata)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
	"go.cadenya.com/cadenya-go/shared"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	toolSetSecret, err := client.ToolSets.Secrets.New(
		context.TODO(),
		"toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
		cadenya.ToolSetSecretNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Metadata: shared.CreateResourceMetadataParam{
				Name: "name",
			},
			Spec: cadenya.ToolSetSecretSpecParam{},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", toolSetSecret.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

tool_set_secret = cadenya.tool_sets.secrets.create(
  "toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  metadata: {name: "name"},
  spec: {}
)

puts(tool_set_secret)

cadenya tool-sets:secrets create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --tool-set-id toolset_01HXKD2E5NQM3T9AYWCFNRMN74 \
  --metadata '{name: name}' \
  --spec '{}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "<string>",
    "externalId": "<string>",
    "labels": {}
  },
  "spec": {
    "value": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'name' => '<string>',
        'externalId' => '<string>',
        'labels' => [
                
        ]
    ],
    'spec' => [
        'value' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"labels\": {}\n  },\n  \"spec\": {\n    \"value\": \"<string>\"\n  }\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "labels": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "value": "<string>"
  },
  "info": {
    "lastUsedAt": "2023-11-07T05:31:56Z",
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

A tool set that talks to a real API needs a credential. You do not put it in the adapter. You store it as a secret, reference it by name, and Cadenya substitutes it when it makes the call.

await client.toolSets.secrets.create(toolSetId, {
  workspaceId,
  metadata: { name: 'ECHO_TOKEN' },
  spec: { value: process.env.ECHO_TOKEN! },
});

_, err := client.ToolSets.Secrets.New(ctx, toolSetID,
	cadenya.ToolSetSecretNewParams{
		WorkspaceID: cadenya.String(workspaceID),
		Metadata: shared.CreateResourceMetadataParam{
			Name: "ECHO_TOKEN",
		},
		Spec: cadenya.ToolSetSecretSpecParam{
			Value: os.Getenv("ECHO_TOKEN"),
		},
	})

cadenya.tool_sets.secrets.create(
  tool_set_id,
  workspace_id: workspace_id,
  metadata: {name: "ECHO_TOKEN"},
  spec: {value: ENV.fetch("ECHO_TOKEN")}
)

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/tool_sets/${TOOL_SET_ID}/secrets" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "name": "ECHO_TOKEN" }, "spec": { "value": "'"${ECHO_TOKEN}"'" } }'

The value goes in and never comes out

spec.value is write-only. The create response redacts it, and so does every read:

const secret = await client.toolSets.secrets.create(toolSetId, {
  workspaceId, metadata: { name: 'ECHO_TOKEN' }, spec: { value: 'super-secret' },
});
console.log(secret.spec.value);  // '': redacted on the way out

const read = await client.toolSets.secrets.retrieve(toolSetId, secretId, { workspaceId });
console.log(read.spec.value);    // '': and on every read after

There is no endpoint that returns a stored value. To change it, update the secret with a new one; you cannot read the old one back to confirm it. Secret names are unique within a tool set. A second secret with the same name is a 409.

Reference it as `${NAME}` in the adapter

Adapter headers take ${SECRET_NAME} placeholders. Cadenya resolves them at call time, so the plaintext lives only in the request Cadenya makes, never in your configuration and never in a response.

// 1. The adapter references a name, not a token.
const toolSet = await client.toolSets.create({
  workspaceId,
  metadata: { name: 'Orders API', externalId: 'orders' },
  spec: {
    adapter: {
      type: 'http',
      http: { baseUrl: 'https://api.example.com', headers: { Authorization: 'Bearer ${ORDERS_TOKEN}' } },
    },
  },
});

// 2. The value is stored separately.
await client.toolSets.secrets.create(toolSet.metadata.id, {
  workspaceId, metadata: { name: 'ORDERS_TOKEN' }, spec: { value: process.env.ORDERS_TOKEN! },
});

Verified end to end against a live HTTP adapter: with the header set to Bearer ${ECHO_TOKEN} and the secret stored, the tool call reached the upstream server carrying the resolved value, the literal ${ECHO_TOKEN} never appeared, and the tool call recorded its source:

"resolvedSecrets": [ { "key": "ECHO_TOKEN", "source": "RESOLVED_SECRET_SOURCE_TOOLSET" } ]

resolvedSecrets on a tool call gives each secret’s key and the source scope it came from. It never carries the value.

Which scope wins

The same name can exist in three places, resolved narrowest-first:

Scope	Set on	Wins when
Objective	one objective	always, over the other two
Tool set	this endpoint	over workspace
Workspace	the workspace	only if nothing narrower has the name

RESOLVED_SECRET_SOURCE_OBJECTIVE beats _TOOLSET beats _WORKSPACE. So a per-user token passed on a single objective overrides a shared service credential for that one run, which is the whole reason objective secrets exist. Store the durable credential here, at the tool set, and let the short-lived one override it per objective.

Store and use secrets

The full precedence story, workspace to objective.

Create a tool set

Where ${SECRET_NAME} goes in an adapter header.

Update a tool set secret

Rotate a value you can never read back.

Create an objective

Objective secrets, which override this one per run.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

The workspace that owns the tool set.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

toolSetId

string

required

The tool set that will own this secret. Accepts the canonical ts_… form or the external_id: form.

Example:

"toolset_01HXKD2E5NQM3T9AYWCFNRMN74"

Body

application/json

metadata

object

required

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

Show child attributes

spec

object

required

Show child attributes

Response

metadata

object

required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

Show child attributes

spec

object

required

Show child attributes

info

object

Tool set secret information

Show child attributes

​The value goes in and never comes out

​Reference it as ${NAME} in the adapter

​Which scope wins

​Related

Store and use secrets

Create a tool set

Update a tool set secret

Create an objective

Authorizations

Path Parameters

Body

Response

The value goes in and never comes out

Reference it as `${NAME}` in the adapter

Which scope wins

Related