[scott-ray-wilson]

Context

Infisical/infisical#8773 adds sessions on behalf of users: a machine identity with a delegation names a user in onBehalfOf when it creates a session, and the proxy then uses that user's personal values. This adds it to the SDK:

• Create: client.agent_vault.sessions.create takes on_behalf_of_user_email or on_behalf_of_user_id, and sends it as onBehalfOf: {"userEmail": ...} or {"userId": ...}. Passing both raises a ValueError before any request. An empty string is sent, not dropped, so the server rejects it instead of the SDK quietly creating the session for the machine identity.
• TTL default: ttl now defaults to None and is left out of the request, so the server picks the default: 7d, or 1h for a session on behalf of a user. Released servers also default a missing ttl to 7d, so existing callers get the same sessions.
• Models: AgentVaultSession.onBehalfOf is the user, as an AgentVaultSessionActor, since the API shapes it like a user actor. It's None for the machine identity's own session, and its id is None once the user is deleted. get, list, update and revoke all return it. It's the last field, so positional construction of the model doesn't change.
• Docstrings: list's search and update's label rule now match the API docs in #8773.

For the reviewer

• Older servers: an Infisical version without #8773 drops onBehalfOf, because zod strips unknown keys. It then creates the session for the machine identity, with a 7d TTL, and the proxy uses the identity's personal values. The create response doesn't include onBehalfOf, so the SDK can't detect this. The create docstring says so. Merge and release this only after #8773 is deployed.
• Not included: listing access bundles with onBehalfOfUserEmail or onBehalfOfUserId, and the delegation endpoints. The SDK has no access bundle or delegation methods yet, so each would be a new resource.

The docs are in Infisical/infisical#9067, a draft until this PR and #8773 ship.

Steps to verify the change

1. Run python -m pytest tests.
2. Run Infisical from #8773. As an Agent Vault admin, set up a delegation for a machine identity that covers a user, and grant one access bundle to both.
3. Log in as the machine identity with the SDK, and call client.agent_vault.sessions.create(access_bundle="<bundle>", on_behalf_of_user_email="<user-email>").
4. Call client.agent_vault.sessions.get with the new session's ID. onBehalfOf is the user, and expiresAt is about an hour away.

Testing done

• Unit: 8 new tests, 28 in total, pass on Python 3.8 through 3.12. With each rule broken on purpose (dropping an empty email, not parsing onBehalfOf, a 7d default, no check for both arguments), only the test written for it fails. The flake8 checks that CI enforces pass.

• Live, against #8773: 33 checks on an isolated stack at e4bb7af1ce, and 35 on a local dev instance whose backend matched the head, b1320d014d, in a throwaway org with a seeded user. They covered:

  • creating by email, by ID, and with an uppercase email
  • the 1h, 7d, 15m and never TTLs
  • onBehalfOf from get, list, update and revoke, and search by the user's name and email
  • the admin's list, the user's own list leaving the sessions out, and a 404 when the user reads one
  • the refusals: no delegation, a bundle the machine identity isn't granted, a user outside the delegation, an empty email, a user calling it, and the delegation removed

  The server logged no errors.

Type

• Fix
• Feature
• Improvement
• Breaking
• Docs
• Chore

Checklist

• Title follows the conventional commit format: type(scope): short description (scope is optional, e.g., fix: prevent crash on sync or fix(api): handle null response).
• Tested locally
• Updated docs (if needed)
• Updated AGENTS.md files (if needed)
• Read the contributing guide

🤖 Generated with Claude Code

[linear]

AGE2-288

[greptile-apps]

Confidence Score: 5/5

[Critical impact] The PR appears safe to merge under the author’s stated backend-deployment requirement.

Summary

Adds Agent Vault sessions on behalf of a user.

• Machine identities can create sessions on behalf of a delegated user.
• Session details show which user the session was started for.

Acknowledged by scott-ray-wilson: older servers ignore onBehalfOf and create the machine identity’s own session. The author requires backend deployment before merging and releasing this change.

Deferred by scott-ray-wilson: access-bundle filters and delegation endpoints are outside this PR because the SDK does not yet expose those resources.

_{Reviews (1) · Last reviewed commit: "feat(agent-vault): create sessions on be..." · Reviewed by Greptile}

[claude]

Beyond the inline finding, I checked that create() depends on post_once in infisical_sdk/infisical_requests.py to leave out None-valued keys. It does: it filters top-level keys with is not None, so a None ttl, label or onBehalfOf is left out of the request, and an empty-string email is still sent.

Extended reasoning...

The change adds on-behalf-of-user session creation to the Agent Vault sessions resource, an optional onBehalfOf field on the AgentVaultSession model, and unit tests. It touches authorization-adjacent behavior: which principal's values a session uses. The ruled-out item is the request layer's None filtering, which matches what the new tests and the PR description assume.

[claude]

🔴 On a server without #8773, callers asking for a session on behalf of a user silently get a 7d session for the machine identity, using the identity's values and full bundle access. create() sends onBehalfOf and returns the server's session without checking it, so a dropped key raises nothing. The docstring calls this accepted, but self-hosted servers can't be upgraded in step with the SDK. Fix: when either on_behalf_of argument is set, call get(id) and check that onBehalfOf is present. If it isn't, revoke the session and raise. Also send ttl="1h" when ttl is None, so a session that slips through still expires as documented.

Why this was flagged

Trigger: a caller on the new SDK runs create(access_bundle=..., on_behalf_of_user_email=...) against an Infisical server older than #8773, for example a self-hosted install not yet upgraded. The PR says zod there strips the unknown onBehalfOf key. agent_vault.py:289-302 builds the body with ttl dropped (None, removed by post_once at infisical_requests.py:220), posts it and returns result.data.session. Nothing checks that the server honoured onBehalfOf. The server then creates an ordinary machine-identity session with its 7d default. The caller gets back a CreatedAgentVaultSession token with no error. So an agent meant to run with user-scoped, 1h access runs with identity-scoped access for a week. On the base branch create() had no on-behalf parameter, so nobody could believe they had a delegated session. The docstring warning at agent_vault.py:266-268 and the PR's 'release only after #8773 is deployed' plan do not protect self-hosted users, whose servers lag SDK releases.

Verification: With ttl defaulting to None, post_once removes the ttl key (infisical_requests.py:218-220). The older server then applies its 7d default. The code returns result.data.session without checking anything (agent_vault.py:289-302). The return type, CreatedAgentVaultSession (api_types.py:566-573), has no onBehalfOf field.

[scott-ray-wilson]

This is fine for now. Agent Vault doesn't have adoption yet, so there's no one on an older server for this to affect, and this PR merges only after Infisical/infisical#8773 is deployed to Cloud. The create docstring covers older self-hosted servers in the meantime.