Provisioner tokens

A provisioner token lets your deployment platform register agent instances without someone authorizing each one in a browser. If your Support assistant starts a new worker, the platform can register that worker and give it its own credential.

The token belongs to one agent. Every instance it registers belongs to that agent, so your approval pipelines treat its requests like any other request from that agent.

flowchart TD
    platform["Deployment platform"] -->|Uses provisioner token| register["Register instances with withHuman"]
    subgraph agent["Support assistant"]
        first["Worker 1<br/>Its own instance credential"]
        second["Worker 2<br/>Its own instance credential"]
    end
    first -->|Approval requests| pipeline["Approval pipelines"]
    second -->|Approval requests| pipeline
    register --> first
    register --> second

Keep the provisioner token with the deployment platform. Give each runtime its own instance credential to send approval requests. The two credentials do different jobs.

New tokens

Open Agents, select Support assistant, then open the menu beside New instance. Select Issue provisioner token. This needs permission to issue credentials for that agent. Only service agents have provisioner tokens; a personal agent's instances each belong to a member, so the menu does not offer one.

The Provisioner tokens tab opens with the new token ready to copy. Copy it now; the secret won't be shown again. Save it in your deployment platform's secret storage and supply it to the registration process when needed.

Instance registration

With the token available in the WITHHUMAN_PROVISIONER_TOKEN environment variable, run this request from your deployment platform.

curl --fail-with-body --silent --show-error \
  https://app.withhuman.ai/api/aap/v1/instances \
  --header "Authorization: Bearer $WITHHUMAN_PROVISIONER_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $WORKER_REGISTRATION_KEY" \
  --data '{"instance_name":"support-worker-01"}'

Use a unique name for each new instance. Here we're registering support-worker-01; the next worker needs a different name. For a self-hosted deployment, replace https://app.withhuman.ai with your deployment's origin.

Every registration needs an Idempotency-Key header. Generate one for each new worker, such as a UUID, and keep it until registration succeeds. If the response is lost, send the same request with the same key: you get back the same instance and credential instead of a second instance. A key works like this for seven days.

The response includes the new instance and its credential. Give the value in credential.token to that runtime's AAP adapter, along with the AAP base URL. For hosted withHuman, that's https://app.withhuman.ai/api/aap. Check credential.expires_at for when the instance credential will stop working.

The instance credential is returned only in this response, or to a retry with the same token and key, so pass it to the runtime before discarding the response. Keep it out of deployment logs. Use this credential for approval requests; keep the provisioner token for registering more instances.

See Create an agent instance for the API details, including optional instance metadata, requesting a shorter credential lifetime, and registering a webhook receiver for runtimes that pause while they wait for a decision.

To give one instance a receiver from the app instead, see Webhook delivery.

Instances and token activity

Open the agent's Instances tab to find support-worker-01. Its credential should be Active. The Agents guide explains checking its requests and managing its access.

Under Provisioner tokens, each row shows the token's identifier, Status, Issued, Last used and Expires. Last used tells you when the token last registered an instance.

Search by token identifier or filter by Active, Expired or Revoked. Use Previous and Next for longer lists and Clear filters to start again. The list shows identifiers, not the token secrets.

Instance removal

When a worker shuts down for good, delete its instance with the same provisioner token and the instance ID from the registration response:

curl --fail-with-body --silent --show-error --request DELETE \
  https://app.withhuman.ai/api/aap/v1/instances/$INSTANCE_ID \
  --header "Authorization: Bearer $WITHHUMAN_PROVISIONER_TOKEN"

Deleting revokes the instance's credential and cancels its requests that are still waiting for a decision, so reviewers stop seeing them. The instance stays under Instances, disabled, for the record, and can't be enabled again. The same token can also read and rename the instances of its agent.

Token replacement and revocation

Use the displayed Expires date to plan a replacement. Issue a new token and update your deployment platform to use it before the old one expires. Once the replacement is in use, revoke the old token.

To revoke a token, open its row's action menu, select Revoke token and confirm. This needs permission to revoke credentials for the agent. The platform can no longer use that token to register instances.

Instances it already registered keep their own credentials. Their access ends when those credentials expire or are revoked, or when the agent or instance is disabled. To remove an existing instance's access, use its controls in Instances.

Registration problems