Machines and AI agents

A machine is a caller that is not a person: a nightly job, a backend, a CI pipeline, or an AI agent. It has no password, no email and no sign-in. It has a name, a kind, roles and permissions of its own, and one or more keys. Use a machine instead of a user API key when the caller should not borrow a person’s identity:

	User API key	Machine
Acts as	The person who made it	Itself
If the person leaves	The key stops	Nothing changes
Permissions	A subset of the person’s	Its own roles and permissions
Who creates it	The person	An administrator, with the secret key
In logs and policies	Looks like the person	`actor.type = "machine"`

Two kinds

Kind	For
`service`	A job, backend or pipeline that runs your code
`agent`	An AI agent: an assistant, an MCP server, an automation that decides what to call

The kind changes nothing about what a machine may do. It is recorded in the token and in $auth.actor, so a policy or a report can tell an agent from a script.

Turn it on

Machines are off until you enable them in the directory settings.

Setting	Meaning	Key	Default
Let this environment have machines	Off, existing keys stop working too	`directory.machines.enabled`	off
Machines per environment	The most machines	`directory.machines.max_machines`	25
Keys per machine	The most active keys one machine may hold	`directory.machines.max_keys_per_machine`	5
Longest a key may live	Days. 0 lets a key never expire	`directory.machines.max_days`	365
Token lifetime	Minutes an access token from the `client_credentials` grant lives	`directory.machines.token_minutes`	15

In Studio

Users & auth → Developers → Machines & agents.

Configure holds the settings in the table above. Turn machines on here first.
New machine asks what it is (a service or an AI agent), its name, its roles and any extra permissions.
Open a machine to see its client ID, change its roles and permissions, disable or delete it, and manage its keys.
New key takes an optional name, an optional list of permissions to limit it to, and how many days it lasts. The key is shown once, next to the client ID, with a copy button.

Create a machine from code

Machines can also be administered with the environment’s secret key, from your server or a script.

import { createClient } from "@pawabase/client";
import { admin } from "@pawabase/client/admin";

const a = admin(createClient({ url, apiKey: "pb_sk_…", environment: "production" }));

await a.roles.define("order-reader", ["orders:read", "orders:list"]);

const bot = await a.machines.create({
  name: "support-agent",
  kind: "agent",
  description: "Answers order questions in the support chat",
  roles: ["order-reader"],
  permissions: ["tickets:write"],     // on top of its roles
});

const key = await a.machines.createKey(bot.id, {
  name: "production",
  scopes: ["orders:read", "tickets:write"],   // narrower than the machine itself
  expiresInDays: 90,
});
key.client_id;   // the machine's id
key.key;         // pbm_…  shown ONCE. Put it in your secret store and nowhere else

a = pb.admin

a.roles.put("order-reader", ["orders:read", "orders:list"])

bot = a.machines.create(
    name="support-agent",
    kind="agent",
    description="Answers order questions in the support chat",
    roles=["order-reader"],
    permissions=["tickets:write"],
)

key = a.machines.create_key(bot["id"], name="production", scopes=["orders:read", "tickets:write"], expires_in_days=90)
key["client_id"]   # the machine's id
key["key"]         # pbm_…  shown ONCE

curl -X POST "$URL/platform/v1/envs/production/auth/machines" \
  -H "apikey: $SECRET_KEY" -H "content-type: application/json" \
  -d '{"name":"support-agent","kind":"agent","roles":["order-reader"]}'

curl -X POST "$URL/platform/v1/envs/production/auth/machines/$MACHINE_ID/keys" \
  -H "apikey: $SECRET_KEY" -H "content-type: application/json" \
  -d '{"name":"production","scopes":["orders:read"],"expires_in_days":90}'

Option	Meaning
`name`	Unique in the environment
`kind`	`service` (default) or `agent`
`roles`	Roles whose permissions the machine holds
`permissions`	Permissions granted directly, on top of its roles
`org`	An organization the machine belongs to. Its tokens carry `org` and `org_role: "member"`
`app_metadata`	Visible to your server and policies, never to the machine’s holder. Appears as `$auth.claims.app`

What a machine can do

A machine’s permissions are its own permissions plus those of each role. A key’s scopes can only narrow that set. orders:* covers orders:read and orders:write. A key with no scopes carries all of the machine’s permissions. There are two ways, and both end in the same kind of token.

Exchange the key for a token

This is the OAuth client_credentials grant. Use it for agents and long-running services: the token is short-lived and carries only what you asked for.

const agent = pawabase.asMachine({
  clientId: process.env.PB_MACHINE_ID!,
  clientSecret: process.env.PB_MACHINE_KEY!,
  scope: "orders:read",          // optional: ask for less than the key allows
});

const { data } = await agent.from("orders").eq("status", "open");

agent = pb.as_machine(
    client_id=os.environ["PB_MACHINE_ID"],
    client_secret=os.environ["PB_MACHINE_KEY"],
    scope="orders:read",
)
agent.from_("orders").execute()

curl -X POST "$URL/auth/v1/token" \
  -H "apikey: $PUBLISHABLE_KEY" -H "content-type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"'$MACHINE_ID'","client_secret":"'$MACHINE_KEY'"}'

The answer:

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "orders:read",
  "machine": { "id": "01J…", "name": "support-agent", "kind": "agent" }
}

scope is the permissions the token carries. Asking for a scope can only reduce them; a permission the key does not allow is dropped, not an error. In TypeScript, asMachine signs in the first time it needs a token, reuses it until 30 seconds before it expires, and signs in again on its own. In Python, as_machine returns a view with one token; take a new view when expires_in runs out. Without an SDK, send the token as Authorization: Bearer <access_token> with the usual apikey header.

Send the key itself

The simplest option for a script. Send the key as the bearer credential, next to the project key:

apikey: pb_pk_…
Authorization: Bearer pbm_…

The edge swaps the key for a 5-minute access token before the request reaches your rules, exactly as it does for a person’s pbu_ key. A revoked key is refused within about 45 seconds.

What the token says

A machine’s token is an ordinary access token with these differences:

Claim	Value
`sub`	The machine’s id
`actor`	`{ "type": "machine", "kind": "agent", "name": "support-agent" }`
`sid`	`machine:<key id>`, so you can see which key signed in
`email`	`null`
`roles`, `perms`	From the machine and the key’s scopes

Rules and policies

Every rule that works for a signed-in user works for a machine, using the machine’s permissions. To tell the two apart, use Compare values in the rule picker with $auth.actor_type:

Only machines: $auth.actor_type equals machine
Only agents: $auth.actor.kind equals agent
Never a machine: $auth.actor_type equals user

Combine it with Has permission as usual. For example, let only the support agent read orders: All of Has permission orders:read, and $auth.actor.name equals support-agent. See Policy context for the full $auth object.

A machine is kind: "user" in $auth.kind so existing policies keep working. If a rule must be for people only (changing a password, deleting an account, approving a payment), require $auth.actor_type equals user.

Account routes that only make sense for a person (/auth/v1/user, sessions, MFA, devices, a person’s own API keys) answer 403 for a machine.

Manage machines

Task	TypeScript	Python
List	`a.machines.list()`	`a.machines.list()`
One machine and its keys	`a.machines.getMachine(id)`	`a.machines.get_machine(id)`
Change	`a.machines.update(id, { roles })`	`a.machines.update(id, roles=[…])`
Stop every key at once	`a.machines.disable(id)`	`a.machines.disable(id)`
Turn it back on	`a.machines.enable(id)`	`a.machines.enable(id)`
New key	`a.machines.createKey(id, { … })`	`a.machines.create_key(id, …)`
Revoke a key	`a.machines.revokeKey(id, keyId)`	`a.machines.revoke_key(id, key_id)`
Delete	`a.machines.delete(id)`	`a.machines.delete_machine(id)`

Listings never include a secret. Each key shows its prefix, scopes, status, expires_at, last_used_at, last_ip and use_count. To rotate a key, create the new key, deploy it, then revoke the old one. A machine can hold several keys for exactly this reason. Disabling a machine refuses its keys at once. A token it already holds works until it expires (at most the token lifetime, 15 minutes by default, or 5 minutes for a bearer key). The events machine.created, machine.updated, machine.deleted, machine.key_created and machine.key_revoked are available to webhooks.

Errors

Status	When
`401 invalid credentials`	Wrong id, wrong key, revoked or expired key, disabled or deleted machine. One answer for all of them, so a caller learns nothing about which
`400`	`client_id` or `client_secret` missing
`422`	Machines are off, the name is taken, the kind is unknown, or a limit is reached
`403`	A machine called a route meant for people

Good practice

Give each agent its own machine. One shared identity makes every log line ambiguous.
Start from no permissions and add only what the agent needs. An agent that answers order questions does not need orders:write.
Put a scope on every key, give it a short life (30 to 90 days), and rotate it.
Keep the key in a secret store or environment variable. Never put it in a prompt, a tool description, or a repository.
For actions with real consequences, require a person: add a rule $auth.actor_type equals user, or have the agent create a request that a person approves.

What this does not do yet

A machine cannot act on behalf of a person. If an agent needs the person’s own access, use that person’s user API key.
There is no token exchange from an outside identity (for example a CI provider’s OIDC token). The key is the credential.

User API keys

Keys that act as a person.

Policy context

Everything a rule can read about the caller.

Getting started

Sign-in methods

Sign-up

Security

People

Developers

Machines and AI agents

Two kinds

Turn it on

In Studio

Create a machine from code

What a machine can do

Exchange the key for a token

Send the key itself

What the token says

Rules and policies

Manage machines

Errors

Good practice

What this does not do yet

User API keys

Policy context

​Two kinds

​Turn it on

​In Studio

​Create a machine from code

​What a machine can do

​Sign in

​Exchange the key for a token

​Send the key itself

​What the token says

​Rules and policies

​Manage machines

​Errors

​Good practice

​What this does not do yet

User API keys

Policy context

Two kinds

Turn it on

In Studio

Create a machine from code

What a machine can do

Sign in

Exchange the key for a token

Send the key itself

What the token says

Rules and policies

Manage machines

Errors

Good practice

What this does not do yet