Skip to main content
OAuth clients are the project-level auth configuration for your own application. Use them when you want users to sign in to your app through MeshAgent, then connect to rooms with the right participant tokens and room grants. Project OAuth client management is controlled by the project OAuth-client roles: oauth_client_creator, oauth_client_inventory, and oauth_client_manager. Project admins receive those roles. Do not use OAuth clients for backend automation or CI. Use API Keys for that. You do not need an OAuth client for MeshAgent Studio, Powerboards, or normal CLI sign-in. Those flows use MeshAgent’s built-in auth.

​
How OAuth clients work

The flow is:
  1. Create an OAuth client for the project.
  2. Send the user through that OAuth flow from your app.
  3. After sign-in, your backend decides which rooms the user should access.
  4. Your backend mints participant tokens for those rooms.
  5. Your app connects to the room with that token.
The OAuth client handles user sign-in. The participant token handles room access.

​
Set up an OAuth client

Use MeshAgent Studio for the main UI flow.
  1. Open OAuth Clients in your project.
  2. Create a new client.
  3. Enter a name for the app.
  4. Add one or more redirect URIs.
  5. Choose the grant types and response types your app uses.
  6. Set the scopes your app should request.
  7. Save the client and copy the client ID and client secret.
The client secret is only shown when the client is created. Store it in your backend secret manager before you close the dialog.

​
What the fields mean

  • Name: a label for the app in MeshAgent Studio
  • Redirect URIs: the callback URLs MeshAgent can send users back to after sign-in
  • Grant types: the OAuth flows your app is allowed to use, such as authorization_code, refresh_token, or client_credentials
  • Response types: the response formats your app expects from the OAuth flow, such as code, token, or id_token
  • Scopes: the OAuth scopes returned in tokens for this client, such as profile:read, rooms:connect, llm:invoke, or secrets:proxy
For project-level LLM proxy access, include the llm:invoke scope. OAuth-authenticated requests to the MeshAgent OpenAI or Anthropic proxy also require Meshagent-Project-Id: <project_id> and a user whose project role satisfies llm_proxy_user, such as a developer, admin, or member with direct LLM proxy access. If you use authorization_code, you need at least one redirect URI.

​
Typical setup

For a typical app with a backend:
  • use authorization_code
  • add refresh_token if you want long-lived sign-in sessions
  • add your callback URL as a redirect URI
  • request the scopes your app actually needs
After the user signs in, keep using your backend for room access. The backend should mint the participant tokens your client uses to join rooms.

​
REST API and SDKs

Use the REST API or SDKs when you want to provision clients programmatically. OAuth clients live under the project:
  • POST /accounts/projects/{project_id}/oauth/clients
  • GET /accounts/projects/{project_id}/oauth/clients
  • PUT /accounts/projects/{project_id}/oauth/clients/{client_id}
  • DELETE /accounts/projects/{project_id}/oauth/clients/{client_id}

​
External OAuth registrations

External OAuth registrations are separate from project OAuth clients. Use OAuth clients when your app needs users to sign in through MeshAgent. Use external OAuth registrations when MeshAgent needs to hold project- or room-scoped integration configuration for an external OAuth provider. External OAuth registrations live under the project or a room:
  • POST /accounts/projects/{project_id}/external-oauth
  • GET /accounts/projects/{project_id}/external-oauth
  • PUT /accounts/projects/{project_id}/external-oauth/{registration_id}
  • DELETE /accounts/projects/{project_id}/external-oauth/{registration_id}
  • POST /accounts/projects/{project_id}/rooms/{room_name}/external-oauth
  • GET /accounts/projects/{project_id}/rooms/{room_name}/external-oauth
  • PUT /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}
  • DELETE /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}

​
Login branding

In Studio, open Account management, select your project, then open OAuth Clients and create or edit a client. Set Login logo URL to an absolute HTTP(S) image URL and choose Login appearance: Light, Dark, or Auto (system). Leave the logo empty to use MeshAgent’s logo. Auto follows the browser’s color preference. These settings also apply to the OAuth consent screen. The same settings are available through the CLI:
For API clients, these optional settings live alongside name in the OAuth client’s metadata object: logo_url and theme (light, dark, or auto). Preserve other metadata entries when updating the object. Remove logo_url to restore the default logo; omitted theme defaults to auto.

​
Email and password login

Deployment administrators can enable email/password login alongside Google and Microsoft in the MeshAgent Helm chart:
It is disabled by default. Enable the email provider in the deployment’s Supabase Auth configuration as well, with email confirmation required. For self-hosted Supabase, set GOTRUE_MAILER_AUTOCONFIRM=false (the local k3s default). New accounts must confirm their email before they can sign in or complete OAuth authorization. Supabase controls signup availability, password policy, rate limits, and email delivery. Allow the router’s /login and /oauth/login URLs (including query parameters) in Supabase’s redirect allow list so confirmation and recovery links return to the login flow. Supabase’s public Auth URL (API_EXTERNAL_URL for self-hosted Supabase) must be reachable by users’ browsers so email links can be opened. Users can enter an email, continue with a password, create an account, or choose Forgot password?. Confirmation and recovery links return to the same branded login flow. Verification-code entry is also supported if your Supabase email templates include {{ .Token }}. Passwords and Supabase session tokens are never included in OAuth client metadata; the router stores the authenticated session in its existing HTTP-only browser session. The live regression test is meshagent-cloud-smoke/meshagent_cloud_smoke/email_login_live_smoke_test.py. Run it with RUN_MESHAGENT_CLOUD_SMOKE=1, MESHAGENT_API_URL, MESHAGENT_PROJECT_ID, SUPABASE_URL, and the Supabase service-role SUPABASE_KEY. It creates and removes a temporary tmp-<random>@timu.com user and OAuth client. Confirmation uses an admin-generated code, and recovery uses an admin-generated link, so delivered email is not required. The test also checks forced light/dark themes, automatic theme changes, custom branding on consent, and the OAuth token exchange.