Skip to main content
OAuth is an advanced room-secret workflow. Use it when a room service or participant needs MeshAgent to:
  • request a user OAuth token
  • store the resulting credential as a room secret
  • refresh that credential when possible
  • retrieve the latest valid token for offline use
If you just need to put an API key or token into a room service, start with Room Secrets instead.

​
CLI commands

Start with the CLI help, then use meshagent room secret oauth when you want to start an OAuth request flow from the CLI:
bash
meshagent room secret --help
meshagent room secret oauth --help
Example:
bash
meshagent room secret oauth \
  --room myroom \
  --from-participant-id provider-agent \
  --client-id YOUR_CLIENT_ID \
  --authorization-endpoint https://provider.example.com/oauth/authorize \
  --token-endpoint https://provider.example.com/oauth/token
This starts the OAuth request from the room. The actual provider sign-in and authorization handoff still happens through the participating client surface.

​
Core OAuth methods

  • request_oauth_token: Request a token, or reuse/refresh one if a valid credential already exists
  • provide_oauth_authorization: Complete or reject the pending authorization request
  • get_offline_oauth_token: Retrieve the latest valid stored token for background use

​
How the OAuth flow works

  1. Your agent or service calls request_oauth_token.
  2. MeshAgent checks whether a valid credential already exists for that room and identity.
  3. If a credential is missing or expired, MeshAgent asks the target participant to authorize access.
  4. The client app completes the provider sign-in flow and calls provide_oauth_authorization.
  5. MeshAgent stores the resulting credential as a room secret and can later refresh or reuse it.

​
Permissions

OAuth uses the room-secrets system, but it has one extra permission layer. When a service or participant joins a room, it does so with a participant token that declares which APIs it may call. For OAuth, request_oauth_token and get_offline_oauth_token check the caller’s SecretsGrant, which acts as an allow-list of OAuth endpoints and client IDs.
  • If the runtime has not narrowed the grant, the default service path uses an empty SecretsGrant.
  • If you want to restrict which providers a service can use, add explicit OAuthEndpoint entries.
Provider and endpoint details change over time, so the examples here use placeholder domains rather than provider-specific URLs. 
from meshagent.api.participant_token import ApiScope, OAuthEndpoint, SecretsGrant

token.add_api_grant(
    ApiScope(
        secrets=SecretsGrant(
            request_oauth_token=[
                OAuthEndpoint(
                    endpoint="https://provider.example.com/oauth/*",
                    client_id="YOUR_CLIENT_ID",
                )
            ]
        )
    )
)
You can express the same restriction in a service manifest:
yaml
ports:
  - num: *
    endpoints:
      - path: /my-agent
        meshagent:
          identity: my-agent
          api:
            secrets:
              request_oauth_token:
                - endpoint: https://provider.example.com/oauth/*
                  client_id: YOUR_CLIENT_ID
If a SecretsGrant exists but no entry matches the requested provider, MeshAgent rejects the OAuth request with a permission error. Other room-secret operations such as set_secret, get_secret, list_secrets, delete_secret, request_secret, and provide_secret are scoped by the caller identity and delegation fields rather than by OAuth endpoint allow-lists.