Secrets

​

Overview

• Request OAuth access tokens (interactive flow) with PKCE by default.
• Fetch a offline (saved) tokens for a participant if one already exists
• List and delete stored secrets for the current room.

Availability: Python SDK and CLI today. Other SDKs may add helpers later.

CLI Note: Room-scoped secrets and OAuth actions are under meshagent oauth2. For project wide or image-pull secrets, use meshagent secret.

​

API Methods

​

list_user_secrets

• Description: List secrets saved to the current room.
• Parameters: None.
• Returns: list[SecretInfo] (id, type, name, delegated_to| None)

meshagent oauth2 list --room=myroom

​

delete_user_secret

• Description: Delete a stored secret by ID.
• Parameters:
  • id: str — secret ID
  • delegated_to: str | None - who the secret is delegated to
• Returns: None

meshagent oauth2 delete --id=SECRET_ID --room=myroom

​

request_oauth_token

• Description: Run an OAuth flow and return an access token after the target participant grants consent. If a valid credential already exists, the server may refresh and return it without prompting the user to sign-in.
• Parameters:
  • oauth: OAuthClientConfig (client_id, authorization_endpoint, token_endpoint, client_secret?, scopes?, no_pkce?)
  • connector: ConnectorRef (optional; use a configured connector instead of raw OAuth settings)
  • from_participant_id: str — participant who must approve
  • redirect_uri: str
  • delegate_to: str | None — save for another participant
  • timeout: int (seconds; default 300)
• Returns: str (access token)
• Notes: Checked against SecretsGrant permissions. PKCE is used unless no_pkce is set on the OAuth config.

meshagent oauth2 request \
  --room=myroom \
  --from-participant-id=PARTICIPANT_ID # can get from meshagent participant list --room=myroom \
  --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 previously saved token for a participant—no prompt shown. Returns None if there isn’t one. This is useful for email based agents that cannot display an interactive UI to the user.
• Parameters:
  • oauth: OAuthClientConfig (same fields as above) or
  • connector: ConnectorRef (optional)
  • delegated_to: str | None — participant the token belongs to
  • delegated_by: str | None — who granted it
• Returns: str | None (access token or None)

offline = await room.secrets.get_offline_oauth_token(
    client_id="your-client-id",
    authorization_endpoint="https://accounts.example.com/o/oauth2/v2/auth",
    token_endpoint="https://oauth2.example.com/token",
    delegated_by="participant_123",
    scopes=["scope1"],
)
if offline is None:
    print("No offline token for participant_123.")
else:
    print("Offline token:", offline)

​

provide_oauth_authorization

• Description: Approve an OAuth prompt by sending the authorization code for a pending request. Use this only if your app shows the user the oauth approval UI (after request_oauth_token is called). For example, an agent might call request_oauth_token inside a tool, if so then the UI must call provide_oauth_authorization to…
• Parameters:
  • request_id: str — ID of the pending request you’re answering
  • code: str — authorization code returned by the provider after the user authenticates
• Returns: None

# Inside your OAuth prompt handler
await room.secrets.provide_oauth_authorization(
    request_id=req.request_id,
    code=auth_code,  # obtained from the provider’s callback
)

​

reject_oauth_authorization

• Description: Deny an OAuth prompt when the user cancels or an error occurs in your approval UI.
• Parameters:
  • request_id: str — ID of the pending request you’re answering
  • error: str — short reason (e.g., “user_cancelled”, “invalid_state”)
• Returns: None

# Inside your OAuth prompt handler 
await room.secrets.reject_oauth_authorization(
    request_id=req.request_id,
    error="user_cancelled",
)

​

Conclusion