Upsert user-scoped secrets (write-only).
const url = 'https://shiftagent.example.com/users/example/secrets';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"secrets":{"CRM_API_KEY":"example-value-vaulted-never-echoed"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://shiftagent.example.com/users/example/secrets \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "secrets": { "CRM_API_KEY": "example-value-vaulted-never-echoed" } }'Vaults alias → value pairs scoped to this user — available to every
conversation the user owns, resolved after message- and
conversation-scoped secrets (message → conversation → user → tenant). Idempotent merge-upsert per alias: existing aliases are
overwritten, others are untouched.
Write-only contract: values are vaulted at the boundary and never
appear in any response, message, event, or log. The agent runtime
receives only {{secret:ALIAS}} placeholders; the egress proxy
resolves them on outbound network calls. The response lists the
user’s aliases and metadata — never values.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Internal user ID.
Request Body required
Section titled “Request Body required ”Body for putUserSecrets — write-only upsert.
object
alias → value pairs to vault. Existing aliases are overwritten; others untouched. Values never appear in any response.
object
Examples
Vault a per-user credential
{ "secrets": { "CRM_API_KEY": "example-value-vaulted-never-echoed" }}Responses
Section titled “ Responses ”Aliases now vaulted for this user — values are never returned.
object
Envelope discriminator.
The page of items.
Whether more items exist beyond this page.
Opaque cursor for the next page (pass as starting_after). Null when has_more is false.
A vaulted secret alias for a user (available to every conversation the user owns). Values are never represented in any schema — write-only at every entry point.
object
The alias the agent references as {{secret:ALIAS}}.
RFC 3339 / ISO 8601 timestamp, UTC.
RFC 3339 / ISO 8601 timestamp, UTC.
Example
{ "object": "list", "data": [ { "object": "user.secret" } ]}Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.
RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.
object
Problem type URI (registry slug).
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
URI reference identifying this occurrence.
Correlation ID for support and log lookup.
On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).
On validation-error, field-level details.
object
JSON pointer to the offending field.
What failed.
Examples
Missing or invalid bearer token
{ "type": "https://shiftagent.example.com/problems/insufficient-scope", "title": "Unauthorized", "status": 401, "detail": "Provide a valid sk_int_ service key or platform JWT.", "request_id": "req_01hzx8auth001"}Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).
RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.
object
Problem type URI (registry slug).
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
URI reference identifying this occurrence.
Correlation ID for support and log lookup.
On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).
On validation-error, field-level details.
object
JSON pointer to the offending field.
What failed.
Examples
Unknown resource
{ "type": "https://shiftagent.example.com/problems/not-found", "title": "Not found", "status": 404, "detail": "No tenant with external_id acme:tenant:999999.", "request_id": "req_01hzx8nf001"}Unprocessable — validation-error (schema/semantic validation failed; errors[] lists JSON-pointer details), role-required (the user has no role assigned, so no conversation context can resolve), or missing-secret (a referenced alias is vaulted at no scope).
RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.
object
Problem type URI (registry slug).
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
URI reference identifying this occurrence.
Correlation ID for support and log lookup.
On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).
On validation-error, field-level details.
object
JSON pointer to the offending field.
What failed.
Examples
Field-level validation failure
{ "type": "https://shiftagent.example.com/problems/validation-error", "title": "Validation error", "status": 422, "detail": "One or more fields failed validation.", "errors": [ { "pointer": "/skill_access/skill_ids/0", "message": "skl_01hzx8unknown does not belong to the tenant's repository." } ], "request_id": "req_01hzx8val001"}User has no role at conversation creation
{ "type": "https://shiftagent.example.com/problems/role-required", "title": "Role required", "status": 422, "detail": "User usr_01hzx8jane001 has no role assigned; assign one before starting conversations.", "request_id": "req_01hzx8role01"}