---
title: "Rotate an agent-bound worker token"
method: POST
path: "/api/agents/{id}/token/rotate"
tags: ["Sessions"]
---

# Rotate an agent-bound worker token

`POST /api/agents/{id}/token/rotate`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/agents/{id}/token/rotate`
- Auth: HTTP bearer

Returns a new token once. The previous token keeps working for `graceSec` (default 300), then expires. Use revoke for a token that must stop now.

## Path parameters

- `id` string, required

## Request body

- object
  - `graceSec` integer
  - `ttlMs` integer: Token lifetime in ms. Omit for the default (no expiry).

## Response `200`

New worker token

- object
  - `agentId` string, required
  - `tokenId` string, required
  - `plaintext` string, required
  - `expiresAt` string, nullable, required: null when the token does not expire
  - `previousExpiresAt` string, required

## Other responses

- `403`: Operator or user credentials required
- `404`: Agent holds no active token

## Changes

- **2026-10-20** `9628ff490c6a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/agents/:id/token/rotate/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)