Personal Access Tokens
Create and manage Personal Access Tokens (PATs) for programmatic access to the AgentStead API.
Personal Access Tokens let you authenticate API calls from scripts, CI pipelines, or any automation without using your account password or session cookie.
Tokens are displayed once at creation. Copy your token immediately — if you lose it, you'll need to revoke it and create a new one.
Creating a token
Open API settings
Go to Settings → API in the AgentStead dashboard.
Click New Token
Give the token a descriptive name — something that identifies what it's for, like deploy-ci or monitoring-script.
Choose scopes
Select the minimum scopes your use case needs:
| Scope | What it allows |
|---|---|
read | List and inspect agents, read logs, check health |
deploy | Start, stop, restart, and deploy agents |
full | All operations including secrets, settings, and backups |
You can select multiple scopes. A token with read + deploy but not full cannot access secrets.
Set an expiry (optional)
Leave blank for a non-expiring token, or set a date. Expired tokens are automatically rejected.
Copy the token
The full token is shown exactly once. It looks like:
x3s_abc123defghijklmnopqrstuvwxyzCopy it now and store it somewhere safe (a password manager, a CI secret, an environment variable).
Using a token
Pass the token in the Authorization header of every request:
curl https://api.agentstead.dev/api/agents \
-H "Authorization: Bearer x3s_your_token_here"const res = await fetch('https://api.agentstead.dev/api/agents', {
headers: {
'Authorization': 'Bearer x3s_your_token_here',
},
});
const { agents } = await res.json();import httpx
headers = {"Authorization": "Bearer x3s_your_token_here"}
r = httpx.get("https://api.agentstead.dev/api/agents", headers=headers)
agents = r.json()["agents"]Revoking a token
Go to Settings → API, find the token by name or prefix, and click Revoke. The token stops working immediately.
Revoke tokens you no longer use, tokens that may have been exposed, and tokens belonging to pipelines you've decommissioned.