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.

​
CLI commands

Start with the CLI help, then use a few common commands:
bash
meshagent room secret --help
meshagent room secret list --room myroom
meshagent room secret set --room myroom --id my-secret --text "token-value"
meshagent room secret oauth --room myroom

​
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. In practice:
  • OAuth request flows are checked against the secrets grant on the participant token
  • secret access also depends on room identity and delegation rules
  • storing or retrieving secrets for another identity may require broader room authority, such as admin access
See Room Secrets, OAuth With Room Secrets, API Scopes, and Packaging and Deploying Services.

​
API reference

Use the methods below to store room secrets, retrieve them, and handle delegated secret or OAuth flows between participants.

​
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(secret_id)

  • 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(secret_id)

  • 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, TypeScript/JavaScript, 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, TypeScript/JavaScript, 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.