Agent Credentials

Two paths

An agent that calls a Syncropel instance over HTTP needs a credential. There are two ways to give it one, and they answer to different failure modes:

The question that picks between them: if this person leaves, should the agent keep working? For an instance's own plumbing, yes — credential it at the instance level. For "my coding agent, spending my budget, acting under my authority" — no, and the principal model makes that automatic.

Path A: instance-level service account

This is the pre-principal path, unchanged and still correct for instance services. Create a dedicated service account with the narrowest scopes that cover the agent's job, mint a bearer, and hand it to the agent as an environment variable:

spl service-account create \
  --name "importer-agent" \
  --actors did:sync:agent:importer \
  --scopes records:read,records:write \
  --with-token

The agent sends Authorization: Bearer <token> on every call. Rotation and revocation are per-token or per-account — see Agent integration and Service accounts for the lifecycle.

Because this credential belongs to the instance and not to any member, offboarding a member never touches it. That is a feature for a fleet importer and a liability for a personal agent — which is what Path B exists for.

Path B: an agent as a slice of a member

Under the principal model, a member's authority is a grant, and grants attenuate. An agent credential in this model is a sub-grant of the member's membership grant: a child grant carrying a subset of the member's scopes, plus caveats the member chooses —

• max_depth — how many further delegation hops the agent may create below itself (0 = none),
• max_fanout — how many direct children it may issue,
• budget — a spend ceiling.

Attenuation is one-directional: the sub-grant can only narrow what the member holds, never widen it. And the chain of authority is on the record — the sub-grant names its ancestors, verified at ingest, so "why can this agent write here?" is answerable by walking records back to the membership.

The guarantee that already works today is the one that matters most: because every credential parented to a membership dies with it, offboarding the member kills their agents' credentials in the same single revocation. spl member revoke <label> reports the cascade explicitly — credentials killed, sub-grants invalidated — and the agent's bearer gets 401 GRANT_REVOKED on its very next request. There is no orphaned-agent problem to remember to clean up.

Mint a sub-grant for your agent with one command:

spl member grant <your-label> --aud did:sync:agent:helper \
  --scopes records:read --max-depth 1 --budget 5

The response carries the agent's bearer and the sub-grant id. The door refuses any sub-grant that names more scope than your membership holds or widens a caveat; revoke one delegation without touching your membership with spl member grant-revoke <your-label> <grant-id>. Over HTTP the same pair is POST /v1/members/{label}/grants and DELETE /v1/members/{label}/grants/{grant_id}.

Adopting an existing agent credential

If you already have a Path-A service account that should have been a member's — say the credential your personal agent has been using — an admin can re-home it without breaking the running agent:

spl member adopt mora --sa sa_1f8e2c9a

This mints a custodial principal for the account's holder and re-parents the credential to a fresh membership grant — the bearer keeps working through the transition, and from that moment offboarding reaches it like any member credential.

Choosing, in one paragraph

Credential standing infrastructure at the instance level and accept that you must revoke it deliberately. Credential person-shaped agents under the person, and offboarding becomes one command with a stated blast radius. When in doubt, ask who should be holding the bag when the credential misbehaves — the instance, or a member — and parent the credential there.

What's next

• Agent integration — dispatching work to agents and building their trust.
• Principals & grants — the grant model these credentials live in.
• Scopes & permissions — scopes, wire grains, caveats, and chain rules.
• Add a teammate — the membership flow the sub-grant hangs off.