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:- Create an OAuth client for the project.
- Send the user through that OAuth flow from your app.
- After sign-in, your backend decides which rooms the user should access.
- Your backend mints participant tokens for those rooms.
- Your app connects to the room with that token.
Set up an OAuth client
Use MeshAgent Studio for the main UI flow.- Open OAuth Clients in your project.
- Create a new client.
- Enter a name for the app.
- Add one or more redirect URIs.
- Choose the grant types and response types your app uses.
- Set the scopes your app should request.
- Save the client and copy the client ID and client secret.
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, orclient_credentials - Response types: the response formats your app expects from the OAuth flow, such as
code,token, orid_token - Scopes: the OAuth scopes returned in tokens for this client, such as
profile:read,rooms:connect,llm:invoke, orsecrets:proxy
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_tokenif you want long-lived sign-in sessions - add your callback URL as a redirect URI
- request the scopes your app actually needs
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/clientsGET /accounts/projects/{project_id}/oauth/clientsPUT /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-oauthGET /accounts/projects/{project_id}/external-oauthPUT /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-oauthGET /accounts/projects/{project_id}/rooms/{room_name}/external-oauthPUT /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}DELETE /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}
Related docs
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 exactlyproject/{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: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.