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 Login Branding. Project administrators can enable branding and set a Company name, an absolute HTTP(S) Logo image URL, and Light or Dark appearance. Branding is disabled by default. The image replaces the MeshAgent logo in the existing 64 × 64 area; leave the URL blank to keep the default logo. When enabled, these settings apply to room IAP login screens for registered room domains in this project. They also apply to OAuth login and consent screens only when the OAuth client’s registered project scope is exactly project/{project_id} for its owning project. Other permission and room/agent scopes may be present. Branding does not apply to clients with project/*, multiple project scopes, a different project’s scope, or no project restriction. Requesting a narrower scope at login does not enable branding for an unrestricted client. These clients keep the default MeshAgent logo and system appearance, with their application name. The settings are stored in the login-branding project settings document: PUT /accounts/projects/{project_id}/settings/login-branding with enabled, company_name, logo_url (HTTP(S) URL or null), and theme (light or dark). The same endpoint supports GET and DELETE. Deleting the document disables branding. Legacy OAuth client logo_url and theme metadata no longer controls login appearance; configure the project’s Login Branding settings instead.

Email login

Deployment administrators can enable email/password and magic-link login alongside Google and Microsoft in the MeshAgent Helm chart:
Both options are disabled by default and can be enabled independently. magicLinkLoginEnabled adds Email me a sign-in link, including when password login is disabled. Users follow the one-time link to sign in without a password; they can also enter a code if the email template includes one. Supabase controls whether new users may sign up through this flow. Configure the Supabase Magic Link email template with {{ .ConfirmationURL }} for links and optionally {{ .Token }} for codes. 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 that unrestricted clients retain default branding, automatic theme changes, and the OAuth token exchange. Project branding eligibility and settings persistence have separate router, cloud, and account-settings widget tests.