Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(agent-vault): give the on-behalf-of and delegation API examples valid values

Scott Wilsonc70a6e69f8bc
diff --git a/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-delegation-router.ts b/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-delegation-router.ts
index 387341ee2f..949871b339 100644
--- a/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-delegation-router.ts
+++ b/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-delegation-router.ts
@@ -12,6 +12,12 @@ import { actorContext } from "./agent-vault-router-fns";
const MAX_DELEGATION_SUBJECTS = 100;
+// Without an example, the docs show all-members, the first value, next to users and groups, which only a selected
+// delegation names.
+const DelegationScopeSchema = z
+ .nativeEnum(AgentVaultDelegationScope)
+ .describe(JSON.stringify({ description: AGENT_VAULT.DELEGATION.scope, example: AgentVaultDelegationScope.Selected }));
+
const DelegationUserSchema = z.object({
id: z.string().uuid().describe(AGENT_VAULT.DELEGATION.userId),
username: z.string().describe(AGENT_VAULT.DELEGATION.username),
@@ -34,7 +40,7 @@ const DelegationSchema = z.object({
name: z.string().describe(AGENT_VAULT.DELEGATION.machineIdentityName)
})
.describe(AGENT_VAULT.DELEGATION.machineIdentity),
- scope: z.nativeEnum(AgentVaultDelegationScope).describe(AGENT_VAULT.DELEGATION.scope),
+ scope: DelegationScopeSchema,
users: DelegationUserSchema.array().describe(AGENT_VAULT.DELEGATION.users),
groups: DelegationGroupSchema.array().describe(AGENT_VAULT.DELEGATION.groups),
createdAt: z.date(),
@@ -147,7 +153,8 @@ export const registerAgentVaultDelegationRouter = async (server: FastifyZodProvi
params: machineIdentityParams,
body: z
.object({
- scope: z.nativeEnum(AgentVaultDelegationScope).describe(AGENT_VAULT.DELEGATION.scope),
+ scope: DelegationScopeSchema,
+ // Without examples, the docs show both lists empty, which a selected delegation can't be.
userIds: z
.string()
.uuid()
@@ -155,7 +162,12 @@ export const registerAgentVaultDelegationRouter = async (server: FastifyZodProvi
.max(MAX_DELEGATION_SUBJECTS)
.default([])
.transform((ids) => [...new Set(ids)])
- .describe(AGENT_VAULT.DELEGATION.userIds),
+ .describe(
+ JSON.stringify({
+ description: AGENT_VAULT.DELEGATION.userIds,
+ example: ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
+ })
+ ),
groupIds: z
.string()
.uuid()
@@ -163,7 +175,12 @@ export const registerAgentVaultDelegationRouter = async (server: FastifyZodProvi
.max(MAX_DELEGATION_SUBJECTS)
.default([])
.transform((ids) => [...new Set(ids)])
- .describe(AGENT_VAULT.DELEGATION.groupIds)
+ .describe(
+ JSON.stringify({
+ description: AGENT_VAULT.DELEGATION.groupIds,
+ example: ["7b1e4f2a-9c3d-4a6b-8e5f-1d2c3b4a5e6f"]
+ })
+ )
})
.superRefine((val, ctx) => {
const named = val.userIds.length + val.groupIds.length;
diff --git a/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-session-router.ts b/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-session-router.ts
index f88999b6c5..5077ec58c0 100644
--- a/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-session-router.ts
+++ b/backend/src/ee/routes/v1/agent-vault-routers/agent-vault-session-router.ts
@@ -187,7 +187,13 @@ export const registerAgentVaultSessionRouter = async (server: FastifyZodProvider
message: "Name the user by userId or by userEmail, not both"
})
.optional()
- .describe(AGENT_VAULT.SESSION.onBehalfOf)
+ // Without an example, the docs' generated request sets both fields, which the refine rejects.
+ .describe(
+ JSON.stringify({
+ description: AGENT_VAULT.SESSION.onBehalfOf,
+ example: { userEmail: "[email protected]" }
+ })
+ )
}),
response: {
200: z.object({
diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts
index eccbbe87c4..0063520e97 100644
--- a/backend/src/lib/api-docs/constants.ts
+++ b/backend/src/lib/api-docs/constants.ts
@@ -4730,7 +4730,7 @@ export const AGENT_VAULT = {
accessBundles: "The access bundle this session carries, by name. A list that accepts exactly one name.",
ttl: "How long the session lasts: a duration such as 30m, 8h or 7d (at least 1m), or never. Defaults to 7d. A session started on behalf of a user defaults to 1h and lasts at most 24h, so never isn't allowed for it.",
onBehalfOf:
- "Start the session on behalf of a user instead of yourself. Only a machine identity whose delegation covers the user can do this. The session can use only an access bundle that both the user and the machine identity can use, and it uses the user's personal values. Name the user by userId or by userEmail.",
+ "Start the session on behalf of a user instead of yourself. Only a machine identity whose delegation covers the user can do this. The session can use only an access bundle that both the user and the machine identity can use, and it uses the user's personal values. Name the user by userId or by userEmail, not both.",
onBehalfOfUserId: "The ID of the user to start the session on behalf of.",
onBehalfOfUserEmail: "The email address of the user to start the session on behalf of.",
token: "The session token. Returned once, at mint, and never again.",