Secrets

​

Overview

• Request an OAuth access token for a participant
• Fetch a saved “offline” token for a participant if one already exists
• List saved secrets in a room
• Delete a secret

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:
  • client_id: str
  • authorization_endpoint: str
  • token_endpoint: str
  • client_secret: str | None (use only if unable to use PKCE)
  • scopes: list[str] | None
  • timeout: int (seconds; default 300)
  • from_participant_id: str — participant who must approve
  • redirect_uri: str
  • no_pkce: bool (default False; set True to disable PKCE)
• Returns: str (access token)
• Notes: Requests are checked against the SecretsGrant to ensure the appropriate permissions are applied.

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:
  • client_id: str
  • authorization_endpoint: str
  • token_endpoint: str
  • client_secret: str | None
  • scopes: list[str] | None
  • timeout: int (seconds; default 300)
  • participant_name: str — whose offline token to fetch
• 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