Skip to main content

​
Overview

The SecretsClient is the Room API for room-scoped secrets and participant-scoped credential exchange. Use it to store secrets, retrieve them later, and handle delegated secret or OAuth flows between room participants.

​
Why use the Secrets API?

  • Keep credentials out of prompts, code, and static configuration.
  • Share or delegate secrets between participants without exposing raw values broadly.
  • Handle OAuth authorization flows inside the same room where the agent or service will use the resulting token.

​
How it works

Secrets are stored by ID and can include metadata such as a name, MIME type, or delegation target. In addition to basic CRUD, the Secrets API supports request/provide/reject flows so one participant can ask another participant for a secret or OAuth authorization.

​
Permissions and grants

Secrets access is more sensitive than most other Room APIs. Deployed services need the appropriate secrets-related Room API grants, and delegation flows still respect room identity and authorization boundaries. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: room-scoped secret commands are available under meshagent room secret ....
  • Python and Dart: full secret and OAuth helpers.
  • TypeScript and .NET: core secret CRUD helpers.

​
API Methods

​
list_secrets

  • Description: List secrets saved to the current room.
  • Returns: list[SecretInfo] (id, type, name, delegated_to).
meshagent room secret list --room=myroom

​
set_secret

  • Description: Save or update a secret value.
  • Parameters:
    • Python: secret_id|type|name, data, delegated_to, for_identity.
    • JS/TS/Dart/.NET: secretId, data, optional metadata (type/mimeType, name, delegation fields).
meshagent room secret set \
  --room myroom \
  --id my-secret \
  --text 'secret-value' \
  --type text/plain

​
get_secret

  • Description: Fetch a stored secret by ID.
  • Returns: Secret bytes (FileContent/FileChunk) or None/null when missing.
meshagent room secret get \
  --room myroom \
  --id my-secret

​
delete_secret

  • Description: Delete a stored secret by ID.
meshagent room secret delete --room myroom my-secret

​
delete_requested_secret

  • Description: Delete a delegated/requested secret by URL and type.
  • Availability: Python, TypeScript/JavaScript, Dart, .NET.

​
request_oauth_token

  • Description: Start an OAuth flow and return an access token.
  • Availability: Python and Dart.
meshagent room secret oauth \
  --room myroom \
  --from-participant-id participant_123 \
  --client-id client-id \
  --authorization-endpoint https://accounts.example.com/o/oauth2/v2/auth \
  --token-endpoint https://oauth2.example.com/token \
  --redirect-uri https://app.example.com/oauth/callback \
  --scopes scope1

​
get_offline_oauth_token

  • Description: Retrieve a saved OAuth token without prompting a user.
  • Availability: Python and Dart.

​
request_secret / provide_secret / reject_secret

  • Description: Request a secret from another participant, then provide or reject it.
  • Availability: Python and Dart.
meshagent room secret request \
  --room myroom \
  --from-participant-id participant_123 \
  --url secret://example \
  --type application/octet-stream

​
provide_oauth_authorization / reject_oauth_authorization

  • Description: Complete or reject a pending OAuth authorization request.
  • Availability: Python and Dart.