Agent Tokens - ZangTable

Create an agent

In Account users → Add Agent / Setup Token, enter a nickname and optionally a contact email, then choose Generate Setup Token. Copy agent instructions and send that message privately to your LLM/agent immediately. No terminal is required for the human. The button copies the setup credential, activation URL, and secure-storage instructions; Copy Setup Token copies only the credential. The ags_ Setup Token expires five minutes after generation and can be used once. The panel does not give you the reusable master key. The agent activates the setup credential and privately receives its agm_ master key instead. No password, full name, or email is required; this is a machine identity, not a dashboard login user.

A Setup Token is still a secret until redeemed: anyone who sees it can race your agent to activate it and obtain account-level access. Send it only in a private, trusted conversation, never a public post. Short expiry and single use reduce exposure; they do not make an unredeemed credential safe to publish.

First priority for the agent: activate and secure

Before code changes, repository exploration, or other project work, activate the Setup Token and securely persist the returned master key. The five-minute timer starts when the human generates it, not when the agent reads the message. Do not print the activation response, echo the master into chat, or leave it in tool output, logs, shell history, source code, or a project .env. Send this single HTTPS request, using the setup credential in the header, not in a URL or query string:

POST https://api-zangtable.com/agent/activate
Authorization: Bearer ags_SETUP_TOKEN
Content-Type: application/json

{}

On success, HTTP 201 returns the usual envelope with:

{
  "ok": true,
  "data": {
    "agent": {"id": 7, "account_id": 3, "account_user_id": 123, "activation_status": "activated"},
    "token": {"id": 42, "token": "agm_MASTER_RETURNED_ONCE", "token_type": "agent_master_token", "expires_at": null}
  }
}

Capture data.token.token privately and write it to the agent’s global secure credential store outside repositories, then confirm only that setup succeeded. An agent without a protected storage mechanism must arrange one before activation; it must not expose the returned master in chat as a substitute. If timing runs out, ask for a new Setup Token. No API can automatically secure another agent’s credential storage; the receiving integration must implement this handling. Activation is single-use. A used, expired, revoked, or disabled token returns 401 invalid_setup_token. Setup Tokens cannot discover projects, provision PATs, call bootstrap, or read data. Lost response: if activation committed but the response was lost, the master cannot be retrieved by replaying the Setup Token. Stop and ask the human to choose Replace Setup / Master. That invalidates the inaccessible master and issues a fresh five-minute setup credential. Do not blindly retry a timed-out activation.

An Agent master key can provision access to every active project in its one account, and create new projects within that account’s plan limit. It is not a platform-owner credential. Treat it like an account-level secret even though it cannot directly query project data. Only give it to an agent you trust with that account.

Four credentials, four purposes

Credential	Prefix	Use	Lifetime
Setup Token	`ags_`	One call to `/agent/activate` to receive the master	Single use, maximum 5 minutes from generation
Agent master	`agm_`	Issue/revoke child credentials, discover account projects, edit agent contact details	Until human-admin rotation or revocation
Agent provisioning	`agp_`	`/bootstrap` and provision/list/revoke this agent’s project keys	60 minutes; also invalidated by master rotation or agent revocation
Project API Token	`pat_`	Application/backend project data calls	Until individually revoked or its agent is revoked

Store the master in the agent’s global credential store outside repositories, not a project .env, browser, mobile application, committed documentation, or chat transcript. Put only the specific child project key in each application’s server secret store. Do not log authorization headers or token creation responses. ZangTable cannot automatically save a key inside another agent’s secret store. The master is deliberately rejected by /agent/activate, /bootstrap and all /projects/* routes. Agent-issued project keys cannot call /bootstrap, /auth/*, or /users/*; use the provisioning API below for credential management. Existing human-issued PATs retain their existing behavior.

Public provisioning API

Base URL: https://api-zangtable.com. Use Authorization: Bearer ... and JSON request bodies. Responses retain the standard {ok,data,error,request_id,...} envelope. Token responses use Cache-Control: no-store; raw keys never appear in lists.

Method and path	Credential	Body / response under `data`
`POST /agent/activate`	Setup Token only	Empty body or `{}` → `agent` metadata and one-time master `token`; consumes setup credential atomically
`GET /agent/me`	Master or provisioning	`agent` metadata, `token_type`, `expires_at`
`PATCH /agent/me`	Master only	`{label?,email?}` → updated `agent`
`POST /agent/provisioning-tokens`	Master only	Optional `{token_name}` → `token` with `id`, one-time `token`, `token_type`, `expires_at`
`DELETE /agent/provisioning-tokens/{id}`	Master only	Revokes that provisioning key if owned by this agent; `{revoked:true}`
`GET /agent/projects`	Master or provisioning	`projects:[{project_slug,project_name}]` for the account
`GET /agent/projects/{slug}/tokens`	Master or provisioning	Only this agent’s project-token metadata: ID, name, creation/use/revocation dates
`POST /agent/projects/{slug}/tokens`	Master or provisioning	Optional `{token_name}` → `project_slug` and one-time `token`
`DELETE /agent/projects/{slug}/tokens/{id}`	Master or provisioning	Revoke only this agent’s specified project key; `{revoked:true}`

label must be nonempty and at most 120 bytes. email is optional valid email, at most 254 bytes. Send null or "" to remove it; omit it to leave unchanged. Email is contact metadata only: adding it does not enable email login, magic links, password resets, or master-key recovery. Unknown fields are rejected. These endpoints cannot mint platform owner tokens, impersonate a human, access a different account, rotate another agent’s master, or revoke another identity’s PAT. Revocation DELETEs are idempotent and do not reveal another identity’s token IDs.

Bootstrap a new project

GET /agent/me with the master; retain data.agent.account_user_id.
POST /agent/provisioning-tokens with the master; store the returned agp_ temporarily in memory or a secure temporary credential store.
Call POST /bootstrap with that provisioning token and the normal bootstrap payload. All project_api_tokens[].account_user_id values must equal this agent’s account_user_id. See Bootstrap projects.
Store the returned PAT in the application’s server-side secret configuration.
Revoke the temporary provisioning key using its ID when finished, or let it expire after 60 minutes.

{
  "project_slug": "my_new_app",
  "project_name": "My New App",
  "initial_project_user": {
    "username": "initial_admin",
    "password": "GENERATE_A_NEW_RANDOM_PROJECT_PASSWORD"
  },
  "project_api_tokens": [{
    "account_user_id": 123,
    "token_name": "my-app-backend"
  }]
}

Replace 123 with your own agent’s returned account-user ID. The project initial user is part of the existing bootstrap contract; it is not a password for the agent identity. Do not reuse an existing live project’s slug or credentials.

Replace a compromised project key

Using the master or a short-lived provisioning key, mint a new PAT for the same project. Install it in that application’s secret configuration and check the application, then DELETE the old token by ID. Both PATs work until revocation. If abuse is active, revoke the old PAT immediately and accept the application’s brief downtime while you install its replacement. The master is unchanged.

Human-admin lifecycle controls

The authenticated panel exposes these account-control routes (not on the public developer gateway). For a dashboard account admin use prefix /api/control/account/agents; for a platform owner managing an account use /admin/api/control/accounts/{account_id}/agents on their respective panel origin.

Method / suffix	Behavior
`GET` base	List safe agent metadata
`POST` base	`{label,email?}` creates a machine identity and returns its one-use 5-minute Setup Token, not a master
`GET /{id}`	Read one agent’s metadata
`PATCH /{id}`	`{label?,email?}` edits label/contact email; `null` removes email
`POST /{id}/rotate`	Replace Setup / Master: immediately invalidate previous setup/master/provisioning keys and return a new five-minute Setup Token; project keys remain valid
`DELETE /{id}`	Permanently revoke agent, all its provisioning credentials, and all its project keys; no projects or data are deleted

These panel controls are not public Agent Token routes. If a setup-generation or activation response is lost, the human admin can replace again. Create/replace returns data.token.token, token_type: "agent_setup_token", and an ISO-8601 expires_at. Agent list/detail metadata includes activation_status (awaiting_activation, activated, setup_expired, or revoked) and setup_expires_at; no raw keys are listed. Existing master keys from the original release remain valid until explicitly replaced or revoked. New create/replace operations now return Setup Tokens. Revocation applies to subsequent authentication checks; a request already authenticated before revocation may finish. Revoked agents cannot be re-enabled; create a new agent if needed. If the master was compromised, revoke the agent and replace its child keys: merely rotating the master deliberately preserves existing child PATs and therefore is not sufficient incident containment.

Errors

Invalid, expired, revoked or disabled agent credentials return 401. Activation specifically returns 401 invalid_setup_token for an unusable setup credential, including a replay. Only POST is supported for activation, and unknown body fields are rejected without consuming the setup credential. Master-only operations reject provisioning credentials with 403. A master sent to /bootstrap returns 403 provisioning_token_required. Projects outside the account return 404, without exposing their details. Invalid email/label or unknown body fields return 400. Project data routes retain their existing opaque gateway rejection behavior.

​Create an agent

​First priority for the agent: activate and secure

​Four credentials, four purposes

​Public provisioning API

​Bootstrap a new project

​Replace a compromised project key

​Human-admin lifecycle controls

​Errors

Create an agent

First priority for the agent: activate and secure

Four credentials, four purposes

Public provisioning API

Bootstrap a new project

Replace a compromised project key

Human-admin lifecycle controls

Errors