Service accounts and keys
Identities a Pi Durable Platform team owns for its apps and scripts: roles, keys, rotation without downtime, disabling and deleting.
A service account is an identity a Pi Durable Platform team owns, for apps, services and scripts. Its keys don't depend on anyone staying on the team: the team's owners and admins are responsible for it. Personal workspaces have no service accounts.
Open Service accounts in the team's sidebar. Members see the accounts; owners and admins create and manage them and their keys.
Create one
Create service account. Its name is 1 to 64 lower-case letters, digits and dashes, unique in the team, such as helpdesk-chat. The audit log shows it as who acted.
Choose its role:
- Member: uses the team's agents, reads its models, MCP servers, usage and limits. Enough for an app that talks to agents someone deployed.
- Editor: also creates and changes agents. An app that gives each of its users an agent (
PUT …/agents/by-key/…) needs it.
A service account is never an owner or admin, and can't change the team.
Open it and create its first key on the Keys tab.
Keys
Keys › Create key. Name it after where it's used, and choose when it expires: 1 to 365 days (90 by default). Keys always expire. The key starts with pdp_sa_ and is shown once; store it in the app's secret store.
An app sends it as a bearer token:
curl https://agents.example.com/v1/teams/support/agents \
-H "Authorization: Bearer $PDP_SA_KEY"Keys can only be created in the browser. Only the team's owners and admins (and platform admins and auditors) see an account's keys; nobody sees a key's secret after it's created.
Rotate a key without downtime
An account can have two active keys at once:
- Create a new key.
- Deploy it where the old one is used.
- Revoke the old key on the Keys tab (Revoke…). It stops working at the next request.
Revoked and expired keys stay listed for 30 days.
What a service account can reach
A service account acts in its own team only, with its role, on the agent routes: listing and creating agents, threads, messages and events, and the team's templates, models, MCP servers, usage and limits. It can't reach GET /v1/me, GET /v1/teams or GET /v1/teams/{team}, which are about a person (403 person_required), and nothing that needs a browser session.
It sees the team's ordinary agents and its own service-managed agents, which only service accounts use. See Agents by key.
Each service account has its own rate limit, REQUESTS_PER_MINUTE (600 a minute by default).
Disable or delete
- Disable service account (in Settings) refuses its keys from the next request. Turn it on again to make them work.
- Delete service account revokes every key at once and frees its name. The audit log keeps its entries.
While a team is archived, its service accounts can be viewed but not changed, and their keys don't work.
A team may have up to 100 service accounts.