> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zangtable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Tokens

> Share a five-minute Setup Token; let the agent privately activate and store its master key.

## 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.

<Warning>
  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.
</Warning>

## 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:

```http theme={null}
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:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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

1. `GET /agent/me` with the master; retain `data.agent.account_user_id`.
2. `POST /agent/provisioning-tokens` with the master; store the returned `agp_`
   temporarily in memory or a secure temporary credential store.
3. 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](/guides/bootstrap-projects).
4. Store the returned PAT in the application's server-side secret configuration.
5. Revoke the temporary provisioning key using its ID when finished, or let it
   expire after 60 minutes.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.