Agents
Rotate an agent key
The new key works at once. By default the old key keeps working for 24 hours (agent.previous_key_valid_until) so the running agent can be redeployed first; invalidate_immediately stops it now. agent_key is returned only in this response.
POST
/
agents
/
{id}
/
rotate-key
Issue a new agent key (shown once) with install commands
curl --request POST \
--url https://use.observer/api/v1/agents/{id}/rotate-key \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"invalidate_immediately": false
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({invalidate_immediately: false})
};
fetch('https://use.observer/api/v1/agents/{id}/rotate-key', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://use.observer/api/v1/agents/{id}/rotate-key"
payload = { "invalidate_immediately": False }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "never_connected",
"online": true,
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"last_heartbeat_at": "2023-11-07T05:31:56Z",
"version": "<string>",
"is_demo": true,
"first_heartbeat_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"previous_key_valid_until": "2023-11-07T05:31:56Z",
"metric_count": 123,
"source_types_active": [
"<string>"
],
"queue_depth": 123,
"otlp_stats": {},
"custom_probes": [
{}
],
"prometheus_url": "<string>",
"install": {
"docker": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"compose": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"kubernetes": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"systemd": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"binary": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
}
},
"env": {}
},
"agent_key": "<string>",
"install": {
"docker": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"compose": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"kubernetes": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"systemd": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"binary": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
}
},
"env": {}
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}Authorizations
An organization API key (obs_pub_…) sent as Authorization: Bearer <key>. Each key carries scopes; an endpoint lists the scope it needs.
Path Parameters
Agent id.
Body
application/json
true: the old key stops working now (a leaked key). Default: it keeps working for 24 hours so the new one can be deployed first.
Response
ok
The agent, without its placeholder install and env (the ones below carry the key).
Show child attributes
Show child attributes
The agent key (obs_live_…). Returned only in this response; Observer stores a hash and cannot show it again.
Install snippets, one per target: docker (docker run), compose, kubernetes (Secret + Deployment manifest), systemd and binary. Without prometheus_url they are for a probes-only agent. The agent key is filled in.
Show child attributes
Show child attributes
The agent's environment as NAME: value (AGENT_KEY, CLOUD_SERVER_URL, and PROMETHEUS_SERVER_URL for a Prometheus agent), for installs the snippets do not cover, such as an existing Compose file or Helm values. The agent key is filled in.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Issue a new agent key (shown once) with install commands
curl --request POST \
--url https://use.observer/api/v1/agents/{id}/rotate-key \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"invalidate_immediately": false
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({invalidate_immediately: false})
};
fetch('https://use.observer/api/v1/agents/{id}/rotate-key', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://use.observer/api/v1/agents/{id}/rotate-key"
payload = { "invalidate_immediately": False }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "never_connected",
"online": true,
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"last_heartbeat_at": "2023-11-07T05:31:56Z",
"version": "<string>",
"is_demo": true,
"first_heartbeat_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"previous_key_valid_until": "2023-11-07T05:31:56Z",
"metric_count": 123,
"source_types_active": [
"<string>"
],
"queue_depth": 123,
"otlp_stats": {},
"custom_probes": [
{}
],
"prometheus_url": "<string>",
"install": {
"docker": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"compose": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"kubernetes": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"systemd": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"binary": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
}
},
"env": {}
},
"agent_key": "<string>",
"install": {
"docker": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"compose": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"kubernetes": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"systemd": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
},
"binary": {
"label": "<string>",
"content": "<string>",
"file": "<string>",
"logs_command": "<string>",
"note": "<string>"
}
},
"env": {}
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}{
"type": "https://docs.use.observer/api/getting-started/errors#forbidden",
"title": "forbidden",
"status": 403,
"detail": "missing scope: write:incidents"
}