> ## Documentation Index > Fetch the complete documentation index at: https://docs.use.observer/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api-reference/openapi.json POST /agents/{id}/rotate-key openapi: 3.1.0 info: title: Observer API version: 1.0.0 description: >- Public API for Observer: read services, metrics, SLOs and SLA statements; manage incidents, maintenance windows, manual metric status, config as code and Observer Agents. Bearer-auth via API keys (obs_pub_…), scoped per key. RFC 7807 problem-detail errors. Cursor pagination. Rate limits are per organization. servers: - url: https://use.observer/api/v1 security: - bearerAuth: [] paths: /agents/{id}/rotate-key: parameters: - name: id in: path required: true description: Agent id. schema: type: string format: uuid post: tags: - agents summary: Issue a new agent key (shown once) with install commands description: >- 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. operationId: rotateAgentKey requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/AgentRotateKeyRequest' responses: '200': description: ok content: application/json: schema: $ref: '#/components/schemas/AgentWithKey' '400': description: >- `invalid_json`: the body is not a JSON object. `invalid_invalidate_immediately`: not a boolean. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: >- `unauthenticated`: no bearer token was sent, or the key is invalid or revoked. `detail` distinguishes the two. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: >- `forbidden`: the key does not carry the scope this endpoint requires. `plan_does_not_permit_api`: the organization's plan does not include the public API. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: >- `not_found`: no agent with that id is available to this key. One owned by another organization, or an id that is not a valid UUID, returns the same response, so a 404 does not confirm that the id is unused. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: >- `rate_limited`: the organization's per-minute or daily request limit is used up (`limit.window` says which). Limits are per organization, shared by every key. The response carries `Retry-After` and `retry_after`, in seconds. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: '`internal_error`: an unhandled server error. Safe to retry.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: - write:agents components: schemas: AgentRotateKeyRequest: type: object properties: invalidate_immediately: type: boolean default: false description: >- 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. AgentWithKey: type: object required: - agent - agent_key - install - env properties: agent: $ref: '#/components/schemas/AgentDetail' description: >- The agent, without its placeholder install and env (the ones below carry the key). agent_key: type: string description: >- The agent key (obs_live_…). Returned only in this response; Observer stores a hash and cannot show it again. install: type: object description: >- 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. properties: docker: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' compose: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' kubernetes: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' systemd: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' binary: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' env: type: object description: >- 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. additionalProperties: type: string Problem: type: object required: - type - title - status example: type: https://docs.use.observer/api/getting-started/errors#forbidden title: forbidden status: 403 detail: 'missing scope: write:incidents' properties: type: type: string format: uri description: Errors reference URI with the title token as the fragment. example: https://docs.use.observer/api/getting-started/errors#forbidden title: type: string description: Stable error token. Branch on this, not on detail. status: type: integer detail: type: string description: Human-readable explanation. Wording may change. retry_after: type: integer description: >- 429 only: seconds until the exhausted window resets (mirrors Retry-After). limit: type: object description: '429 only: which organization limit was hit.' properties: scope: type: string enum: - organization window: type: string enum: - minute - day max: type: integer plan: type: string errors: type: array description: >- Validation failures (config_invalid, invalid_customer_targeting): one entry per problem. items: type: object properties: path: type: string message: type: string warnings: type: array description: >- config_invalid only: the same non-fatal warnings a successful apply returns. items: type: object properties: path: type: string message: type: string unknown_customers: type: array description: >- unknown_customers only: the submitted values that matched no customer in your organization. items: type: string referenced_by: type: object description: >- in_use only: what depends on the object (slos, pages: lists of { id, config_key, name }; subscribers: a count). quota: type: object description: >- quota_exceeded / feature_locked on a create only: the plan limit that blocked it. properties: capability: type: string used: type: - integer - 'null' cap: type: - integer - 'null' plan: type: - string - 'null' upgrade: type: object description: >- Plan-limit problems only, when a higher plan lifts the limit: the smallest such plan and the pricing page. properties: plan: type: string label: type: string url: type: string format: uri AgentDetail: allOf: - type: object required: - id - name - status - online - created_at properties: id: type: string format: uuid name: type: string description: >- Config documents name the agent a metric runs on by this (metrics[].agent). description: type: - string - 'null' status: type: string enum: - never_connected - online - offline - revoked description: >- never_connected: no heartbeat yet (installed agents report within about a minute). online: a heartbeat in the last 90 seconds. offline: it has connected before but has been silent for over 90 seconds. revoked: its key is rejected (console kill switch). online: type: boolean description: status is online. last_heartbeat_at: type: - string - 'null' format: date-time description: Last heartbeat. version: type: - string - 'null' description: Agent version from its last heartbeat. is_demo: type: boolean description: Seeded demo agent; nothing runs it. created_at: type: string format: date-time - type: object properties: first_heartbeat_at: type: - string - 'null' format: date-time description: 'First heartbeat ever: when the install first connected.' started_at: type: - string - 'null' format: date-time description: When the running agent process started. revoked_at: type: - string - 'null' format: date-time previous_key_valid_until: type: - string - 'null' format: date-time description: >- After a graceful key rotation: the old key keeps working until this time. null when no old key is valid. metric_count: type: integer description: Metrics assigned to this agent. source_types_active: type: array items: type: string description: Probe types the agent reported running in its last heartbeat. queue_depth: type: integer description: Samples buffered on the agent, not yet delivered. otlp_stats: type: - object - 'null' description: Latest OTLP receiver stats, when the agent runs the receiver. custom_probes: type: array description: >- Custom probes registered on the agent (name, description, has_config_schema), from its last heartbeat. items: type: object prometheus_url: type: - string - 'null' description: Prometheus base URL recorded for the agent, if it reads PromQL. install: type: object description: >- 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. Here with the ${AGENT_KEY} placeholder: the key is only returned by create and rotate-key. properties: docker: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' compose: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' kubernetes: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' systemd: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' binary: type: object required: - label - content properties: label: type: string file: type: - string - 'null' description: >- Suggested file name, when the snippet is a file (Compose, Kubernetes manifest, systemd). content: type: string description: >- Ready to run or save. Carries the agent key, or the ${AGENT_KEY} placeholder outside create / rotate-key. logs_command: type: - string - 'null' description: Where to read the agent's logs for this install. note: type: - string - 'null' env: type: object description: >- 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. AGENT_KEY is the ${AGENT_KEY} placeholder here. additionalProperties: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: obs_pub_ description: >- An organization API key (obs_pub_…) sent as `Authorization: Bearer `. Each key carries scopes; an endpoint lists the scope it needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.