curl --request POST \
--url https://api.example.com/agents/{agent_id}/internal-key \
--header 'Content-Type: application/json' \
--data '
{
"replace": false,
"replacement_idempotency_key": "<string>"
}
'import requests
url = "https://api.example.com/agents/{agent_id}/internal-key"
payload = {
"replace": False,
"replacement_idempotency_key": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({replace: false, replacement_idempotency_key: '<string>'})
};
fetch('https://api.example.com/agents/{agent_id}/internal-key', 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://api.example.com/agents/{agent_id}/internal-key",
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([
'replace' => false,
'replacement_idempotency_key' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"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://api.example.com/agents/{agent_id}/internal-key"
payload := strings.NewReader("{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://api.example.com/agents/{agent_id}/internal-key")
.header("Content-Type", "application/json")
.body("{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/agents/{agent_id}/internal-key")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent_id": "<string>",
"agent_api_key_id": "<string>",
"agent_api_key": "<string>"
}{
"agent_id": "<string>",
"agent_api_key_id": "<string>",
"agent_api_key": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Provision an Internal Credential
Issue a server-generated internal credential for an agent. Requires a provider-authenticated principal with agent update permission; agent credentials are refused. 201 returns a newly issued credential. 200 returns the same credential again when it was issued within the replay window, for a caller that lost the response. Otherwise an existing credential yields 409 unless replace is true, which issues a new credential and revokes every existing internal credential of the agent. A replacement with replacement_idempotency_key is made once: a later request with the same agent and key returns the same credential with 200 while it has not been revoked and is within the replacement replay window, and yields 409 otherwise or when the key was used for a different agent.
curl --request POST \
--url https://api.example.com/agents/{agent_id}/internal-key \
--header 'Content-Type: application/json' \
--data '
{
"replace": false,
"replacement_idempotency_key": "<string>"
}
'import requests
url = "https://api.example.com/agents/{agent_id}/internal-key"
payload = {
"replace": False,
"replacement_idempotency_key": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({replace: false, replacement_idempotency_key: '<string>'})
};
fetch('https://api.example.com/agents/{agent_id}/internal-key', 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://api.example.com/agents/{agent_id}/internal-key",
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([
'replace' => false,
'replacement_idempotency_key' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"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://api.example.com/agents/{agent_id}/internal-key"
payload := strings.NewReader("{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://api.example.com/agents/{agent_id}/internal-key")
.header("Content-Type", "application/json")
.body("{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/agents/{agent_id}/internal-key")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"replace\": false,\n \"replacement_idempotency_key\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent_id": "<string>",
"agent_api_key_id": "<string>",
"agent_api_key": "<string>"
}{
"agent_id": "<string>",
"agent_api_key_id": "<string>",
"agent_api_key": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Path Parameters
Body
Callers choose only whether to replace; the key value is always server-generated.
Issue a new credential and revoke every existing internal credential of the agent in the same transaction. Pods still holding a revoked credential stop authenticating immediately, so plan a restart with the new value. Without this, an existing credential yields 409 unless it was issued within the replay window.
Requires replace. Binds this replacement to a caller-chosen key that is unique across all agents, such as a UUID. The first request with the key replaces the credential. A later request with the same agent and key returns that same credential with 200 and does not rotate again, while the credential has not been revoked and is within the replacement replay window. Otherwise, and when the key was used for a different agent, it yields 409.
1 - 64^[A-Za-z0-9._:-]+$Response
Replay of a recently issued internal credential, or of the credential a replacement with the same replacement_idempotency_key issued

