Set a secret

⚠️

Preview — this feature is being built; the design below is the spec.

PUT https://app.syntic.ai/v1/vaults/{vault_id}/secrets/{name}

Create a secret, or replace its value. The value is encrypted with your organization’s key before storage and is never returned by any endpoint, log or trace. Restrict where it may be sent with allowed_destinations.

For how this fits into a full workflow, see Credential vaults.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`syntic-beta`	Yes, while in preview	`agents-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Description
`vault_id`	string	The vault id, starting with `vlt_`.
`name`	string	1 to 64 letters, digits, `-` and `_`.

Body parameters

Parameter	Type	Required	Notes
`value`	string	Yes	The secret, up to 16 KB.
`allowed_destinations`	array of strings	No	Host names, `*.` wildcards allowed. Strongly recommended.

Response

200 OK, Content-Type: application/json

{
  "name": "crm-token",
  "hint": "…9f2a",
  "allowed_destinations": [
    "mcp.example.com"
  ],
  "created_at": "2026-11-03T09:00:00Z",
  "updated_at": "2026-11-05T09:00:00Z",
  "last_used_at": "2026-11-05T10:00:03Z"
}

Examples

curl -sS -X PUT https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
      "value": "crm_live_REPLACE_ME",
      "allowed_destinations": [
        "mcp.example.com"
      ]
    }'

import os
 
import requests
 
resp = requests.put(
    "https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "agents-2026-11-01",
    },
    json={
        "value": "crm_live_REPLACE_ME",
        "allowed_destinations": ["mcp.example.com"],
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'syntic-beta': 'agents-2026-11-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "value": "crm_live_REPLACE_ME",
    "allowed_destinations": [
      "mcp.example.com"
    ]
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "value": "crm_live_REPLACE_ME",
  "allowed_destinations": [
    "mcp.example.com"
  ]
}`)
	req, err := http.NewRequest("PUT", "https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("syntic-beta", "agents-2026-11-01")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "value": "crm_live_REPLACE_ME",
              "allowed_destinations": [
                "mcp.example.com"
              ]
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("syntic-beta", "agents-2026-11-01")
            .header("Content-Type", "application/json")
            .method("PUT", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Headers.Add("syntic-beta", "agents-2026-11-01");
request.Content = new StringContent("""
    {
      "value": "crm_live_REPLACE_ME",
      "allowed_destinations": [
        "mcp.example.com"
      ]
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "value": "crm_live_REPLACE_ME",
  "allowed_destinations": [
    "mcp.example.com"
  ]
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'syntic-beta: agents-2026-11-01',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true));

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/vaults/vlt_01JC2B4D6F8H0K2M4P6R/secrets/crm-token")
req = Net::HTTP::Put.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["syntic-beta"] = "agents-2026-11-01"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "value": "crm_live_REPLACE_ME",
    "allowed_destinations": [
      "mcp.example.com"
    ]
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
400	`invalid_request_error`	`invalid_secret_name`	Disallowed characters.
400	`invalid_request_error`	`secret_too_large`	Value over 16 KB.
403	`permission_error`	`role_required`	The key’s creator is not an Administrator or Owner.
404	`not_found_error`	`vault_not_found`	No vault with that id in this workspace.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Who may call this

Creating vaults and writing or deleting secrets needs a key created by an Administrator or Owner. Any key in the workspace may list vaults and read secret names, so developers can wire up agents without ever handling values.

Each write records a vault.secret_written audit event; the value itself is never logged.

Delete a secret

Delete a vault List secrets

Was this page helpful?