> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Clients

> Create project-owned OAuth clients for your app and connect them to participant-token issuance.

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](./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](../rest_api/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](../interfaces/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](../rest_api/participant_tokens) your client uses to join rooms.

## REST API and SDKs

Use the [REST API](../rest_api/overview) 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}`

## Related docs

* [Projects](./projects)
* [API Keys](./api_keys)
* [Participant Tokens](../rest_api/participant_tokens)
* [API Scopes](../rest_api/api_scopes)
* [MeshAgent Studio](../interfaces/meshagent_studio)

## 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:

```bash theme={null}
meshagent oauth-client update CLIENT_ID --logo-url https://example.com/logo.svg --theme dark
meshagent oauth-client update CLIENT_ID --clear-logo --theme auto
meshagent oauth-client get CLIENT_ID
```

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:

```yaml theme={null}
meshagent:
  router:
    emailPasswordLoginEnabled: true
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.