Skip to content
ZUTAX ZUTAX Documentation

Exchange a single-use bootstrap token for a long-lived agent API key

POST
/api/public/v1/agents/register/exchange
Code sample: cURL 
curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/agents/register/exchange' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "bootstrap_token": "ztx_bootstrap_live_8f2a7d5c9e1b4a63"
}'

Called once by the on-prem Connector Agent during registration. The bootstrap token (issued by the workspace admin via POST /api/v1/…/integrations/agents/register) is exchanged for a long-lived workspace API key carrying scope agent:write. The raw API key is returned ONCE; the agent must persist it to OS secret storage before exiting.

Request Body required

Section titled “Request Body required ”
Media type application/json
AgentBootstrapExchangeInput

The agent presents the single-use bootstrap token to exchange it for a long-lived API key (scope agent:write).

object
bootstrap_token
required
Bootstrap Token
string
>= 32 characters <= 256 characters
Examples
Example Exchange bootstrap token

Register an on-prem connector agent

{
  "bootstrap_token": "ztx_bootstrap_live_8f2a7d5c9e1b4a63"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/json
AgentBootstrapExchangeResponse
object
agent_id
required
Agent Id
string format: uuid
api_key
required
Api Key
string
workspace_id
required
Workspace Id
string format: uuid
tenant_id
required
Tenant Id
string format: uuid
Examples
Example Agent key issued

Long-lived agent API key response

{
  "agent_id": "a9ce860b-fc65-4784-b7e5-1f3fc311f8ce",
  "api_key": "ztx_live_agent_6mdu0qk3x4ys9r2fhq",
  "workspace_id": "6c4e2b55-6ed1-44ec-b7c5-4f7a2b701c62",
  "tenant_id": "f95d2e39-329d-4bb3-88e2-6622f0f6cb8a"
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examples
Example Sample response

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}