Skip to content

createAgentToken

POST
/agent/tokens
curl --request POST \
  --url http://localhost:8080/api/v1/agent/tokens \
  --header 'Content-Type: application/json' \
  --cookie hs_session=<hs_session> \
  --data '{ "name": "example", "agentKind": "hermes", "preset": "fetcher", "scopes": [ "people:read" ], "platforms": [ "instagram" ] }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 60 characters
agentKind
required
string
Allowed values: hermes openclaw other
preset
string
default: helper
Allowed values: fetcher helper full
scopes

Overrides preset when set.

Array<string>
Allowed values: people:read people:write circles:read circles:write shares:write feed:read tasks:work ingest:write
platforms
Array<string>
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial

Responses

Section titled “Responses”

201

Section titled “201”

Token created. token and setup are returned once.

Media typeapplication/json
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
name
required
string
agentKind
required
string
Allowed values: hermes openclaw other
scopes
required
Array<string>
Allowed values: people:read people:write circles:read circles:write shares:write feed:read tasks:work ingest:write
platforms
Array<string> | null
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
tokenPrefix
required
string
token

Only on create.

string
setup

Copy-paste setup for the Agents screen. Returned once, with the token inlined.

object
restBaseUrl
required
string format: uri
mcpUrl
required
string format: uri
hermesConfigYaml
required
string
openclawConfigJson5
required
string
openclawCli
string
envBlock
required

HOMESTEAD_URL=… and HOMESTEAD_TOKEN=… lines.

string
skillInstall
object
hermes
string
openclaw
string
createdAt
required
string format: date-time
lastUsedAt
One of:
string format: date-time
revokedAt
One of:
string format: date-time

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "agentKind": "hermes",
  "createdAt": "2026-09-20T09:00:00.000Z",
  "id": "tok_01j9cx6fz4dthpcvht9zhkf4g4",
  "lastUsedAt": "2026-10-17T08:54:00.000Z",
  "name": "Hermes on homeserver",
  "platforms": [
    "instagram",
    "facebook",
    "xiaohongshu"
  ],
  "revokedAt": null,
  "scopes": [
    "people:read",
    "people:write",
    "circles:read",
    "circles:write",
    "feed:read",
    "tasks:work",
    "ingest:write"
  ],
  "setup": {
    "envBlock": "HOMESTEAD_URL=http://localhost:8080/api/v1\nHOMESTEAD_TOKEN=hst_demoDemoDemoDemoDemoDemoDemoDemoDemoDemo12\n",
    "hermesConfigYaml": "mcp_servers:\n  homestead:\n    url: \"http://localhost:8080/mcp\"\n    headers:\n      Authorization: \"Bearer hst_demoDemoDemoDemoDemoDemoDemoDemoDemoDemo12\"\n    timeout: 120\n    connect_timeout: 30\n",
    "mcpUrl": "http://localhost:8080/mcp",
    "openclawCli": "openclaw homestead add --url http://localhost:8080/api/v1",
    "openclawConfigJson5": "{\n  mcp: {\n    servers: {\n      homestead: {\n        url: \"http://localhost:8080/mcp\",\n        transport: \"streamable-http\",\n        headers: { Authorization: \"Bearer hst_demoDemoDemoDemoDemoDemoDemoDemoDemoDemo12\" },\n        enabled: true,\n        requestTimeoutMs: 120000,\n      },\n    },\n  },\n}\n",
    "restBaseUrl": "http://localhost:8080/api/v1",
    "skillInstall": {
      "hermes": "hermes skills install homestead",
      "openclaw": "openclaw skills install homestead"
    }
  },
  "token": "hst_demoDemoDemoDemoDemoDemoDemoDemoDemoDemo12",
  "tokenPrefix": "hst_demo"
}