Create a secret

POST

projects

{projectId}

secrets

Create a secret

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "value": "<string>",
  "description": "<string>",
  "brokerHosts": [
    "<string>"
  ],
  "brokerHeader": "<string>",
  "brokerTemplate": "<string>",
  "sharing": "project"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/secrets"

payload = {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>",
    "brokerHosts": ["<string>"],
    "brokerHeader": "<string>",
    "brokerTemplate": "<string>",
    "sharing": "project"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    value: '<string>',
    description: '<string>',
    brokerHosts: ['<string>'],
    brokerHeader: '<string>',
    brokerTemplate: '<string>',
    sharing: 'project'
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/secrets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/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([
    'name' => '<string>',
    'value' => '<string>',
    'description' => '<string>',
    'brokerHosts' => [
        '<string>'
    ],
    'brokerHeader' => '<string>',
    'brokerTemplate' => '<string>',
    'sharing' => 'project'
  ]),
  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;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/secrets"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/secrets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "delivery": "brokered",
  "sharing": "user",
  "lastDeliveredAt": 123,
  "createdAt": 123,
  "updatedAt": 123,
  "createdByUserId": "<string>",
  "updatedByUserId": "<string>",
  "brokerHosts": [
    "<string>"
  ],
  "brokerHeader": "<string>",
  "brokerTemplate": "<string>",
  "ownerUserId": "<string>"
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Headers

Idempotency-Key

string

Retry-safe create key. Replaying the SAME key with the SAME body returns the original resource instead of creating a second one; reusing it with a DIFFERENT body is a 409. Worth passing: a retried create without one fails as a name conflict with the row the first attempt already made.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

Body

application/json

The secret to create.

THE VALUE TRAVELS IN THIS BODY and becomes visible to whatever makes the call — its process, its logs, its shell history. Supply it from a file or an environment variable rather than pasting it into a command.

name

string

required

Environment-variable name. Immutable — renaming is delete-and-recreate.

Maximum string length: 64

Pattern: ^[A-Z_][A-Z0-9_]*$

value

string

required

The credential. Stored encrypted; no route ever returns it. NOT trimmed — a trailing newline is meaningful in a PEM block, and rewriting what you sent would present as 'the key is wrong' with nothing to look at.

Maximum string length: 65536

delivery

enum<string>

required

Required, with no default: a caller who has not said whether the value ends up inside the sandbox has not made the decision this field exists for. See Secret.delivery.

Available options:

brokered,

materialized

description

string

Maximum string length: 500

brokerHosts

string[]

Required for brokered, forbidden for materialized. Exact hostnames — no scheme, no port, no wildcard: the proxy matches a host, and a URL installs a rule that silently never fires.

Required array length: 1 - 10 elements

brokerHeader

string

Required for brokered, forbidden for materialized. e.g. Authorization.

Maximum string length: 64

brokerTemplate

string

Required for brokered, forbidden for materialized. The header value with {} where the secret goes, e.g. Bearer {}. A template without {} is rejected: it installs a constant header that never carries the credential.

Maximum string length: 256

Defaults to project. A non-admin asking for it is refused rather than downgraded to personal — a silent downgrade looks like success and then reaches nobody else's sessions.

Available options:

user,

project

Response

The created secret, as metadata.

A project credential — METADATA ONLY, always. There is no value field on this schema and no route that returns one: a secret is written and delivered into a run, never read back.

string

required

projectId

string

required

name

string

required

The environment-variable name (^[A-Z_][A-Z0-9_]*$). This IS the secret's identity: what a materialized delivery exports, what a workflow references, and what stays stable across a rotation. Immutable.

description

string | null

required

delivery

enum<string>

required

brokered — the sandbox's egress proxy injects the value as a request header OUTSIDE the VM, so the box never holds it. Prevents EXTRACTION, not USE: any process in the box can call the bound host while the policy is live, and it works for HTTPS APIs only (domain rules bind on ports 80/443). materialized — a real environment variable inside the box, which is the only thing a CLI can read; EXTRACTABLE BY DESIGN.

Available options:

brokered,

materialized

project — admin-managed, delivered to every member's sessions. user — personal, delivered ONLY in sessions its owner starts and silently absent from anyone else's run of the same environment. Immutable.

Available options:

user,

project

lastDeliveredAt

integer | null

required

When this secret was last HANDED TO a run — not when it was last used. Brokered use is unobservable by construction (the proxy injects the header; the request is never seen here), so used would be a number nobody can honestly produce. null means nothing has been recorded, which is not the same as never delivered.

createdAt

integer

required

updatedAt

integer

required

createdByUserId

string

required

updatedByUserId

string

required

brokerHosts

string[]

Brokered only: the exact hostnames the header is injected on.

brokerHeader

string

Brokered only: the header name.

brokerTemplate

string

Brokered only: the header value, with {} where the secret goes.

ownerUserId

string

Personal secrets only. Project-shared rows have no owner.

⌘I

Create a secret

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "value": "<string>",
  "description": "<string>",
  "brokerHosts": [
    "<string>"
  ],
  "brokerHeader": "<string>",
  "brokerTemplate": "<string>",
  "sharing": "project"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/secrets"

payload = {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>",
    "brokerHosts": ["<string>"],
    "brokerHeader": "<string>",
    "brokerTemplate": "<string>",
    "sharing": "project"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    value: '<string>',
    description: '<string>',
    brokerHosts: ['<string>'],
    brokerHeader: '<string>',
    brokerTemplate: '<string>',
    sharing: 'project'
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/secrets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/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([
    'name' => '<string>',
    'value' => '<string>',
    'description' => '<string>',
    'brokerHosts' => [
        '<string>'
    ],
    'brokerHeader' => '<string>',
    'brokerTemplate' => '<string>',
    'sharing' => 'project'
  ]),
  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;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/secrets"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/secrets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"value\": \"<string>\",\n  \"description\": \"<string>\",\n  \"brokerHosts\": [\n    \"<string>\"\n  ],\n  \"brokerHeader\": \"<string>\",\n  \"brokerTemplate\": \"<string>\",\n  \"sharing\": \"project\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "delivery": "brokered",
  "sharing": "user",
  "lastDeliveredAt": 123,
  "createdAt": 123,
  "updatedAt": 123,
  "createdByUserId": "<string>",
  "updatedByUserId": "<string>",
  "brokerHosts": [
    "<string>"
  ],
  "brokerHeader": "<string>",
  "brokerTemplate": "<string>",
  "ownerUserId": "<string>"
}

API Guides

Endpoints

Authorizations

Headers

Path Parameters

Body

Response