# How to Configure Plane Settings: Complete Guide to Instance, Workspace, and Profile Management

> Learn to configure Plane settings for Instance, Workspace, and Profile management. Our guide covers UI and API configurations for seamless operation.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Plane organizes configuration into three distinct layers—Instance, Workspace, and Profile—each managed through specific UI entry points in the React frontend and backed by dedicated Django API endpoints and MobX state management.**

Configuring Plane settings in the `makeplane/plane` repository requires navigating its hierarchical architecture that separates global instance controls from workspace-specific defaults and personal user preferences. This system implements distinct React components, custom hooks, and backend serializers to handle everything from SMTP configuration to API token generation.

## Understanding Plane's Three-Layer Settings Architecture

Plane divides configuration into **Instance**, **Workspace**, and **Profile** settings, each serving different administrative scopes and user roles.

- **Instance Settings**: Global configurations including email SMTP, authentication providers, and feature flags. Accessible only to instance administrators via the **God mode** panel as noted in the root [`README.md`](https://github.com/makeplane/plane/blob/main/README.md).
- **Workspace Settings**: Workspace-wide defaults such as default issue types, webhook URLs, and member invite policies. Managed through the gear icon in [`apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx).
- **Profile Settings**: Personal preferences including notification settings, password management, and API tokens. Accessed via the user avatar menu defined in [`apps/web/core/components/workspace/sidebar/user-menu-root.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/user-menu-root.tsx).

The backend persists these layers differently: Instance settings use Django's settings module and the `Instance` model, while workspace and profile settings rely on the `WorkspaceSerializer` and user-specific endpoints.

## Configuring Instance Settings (God Mode)

Instance administrators configure global behavior through the God mode interface.

1. Navigate to **Settings → Instance** from the God-mode sidebar (visible only to users with instance admin privileges).
2. Toggle services such as email SMTP or authentication providers.
3. Changes persist immediately to the Django settings model and the `Instance` database table.

This layer controls deployment-wide features and requires direct database access for initial setup.

## Managing Workspace Settings

Workspace settings define defaults for all projects within a workspace and are managed through a dedicated drawer interface.

### Accessing the Workspace Settings Drawer

The entry point resides in [`apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx). Click the **gear** icon in the workspace sidebar header to open the settings drawer.

The drawer renders categories defined in [`apps/web/core/components/settings/workspace/sidebar/item-categories.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/settings/workspace/sidebar/item-categories.tsx), including tabs for General, Members, Webhooks, Integrations, and Import/Export.

### Saving Workspace Configuration Changes

Updates flow through the `useUserSettings` hook defined in [`apps/web/core/store/user/settings.store.ts`](https://github.com/makeplane/plane/blob/main/apps/web/core/store/user/settings.store.ts). When modifying workspace properties:

```typescript
// Example: Updating a workspace webhook URL
await fetch(`/api/v1/workspaces/${workspaceId}/webhooks/`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: newWebhookUrl }),
});
await fetchCurrentUserSettings(); // Refresh the MobX store

```

The hook synchronizes the `currentUserSettings` observable across all components, ensuring UI consistency after updates.

## Customizing Profile Settings

Personal configuration manages notification preferences, security credentials, and API access.

### Navigating Profile Settings Categories

Open the profile modal via the user avatar menu (the Settings icon in [`apps/web/core/components/workspace/sidebar/user-menu-root.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/user-menu-root.tsx)). The sidebar categories render through [`apps/web/core/components/settings/profile/sidebar/item-categories.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/settings/profile/sidebar/item-categories.tsx), offering tabs for General, Preferences, Security, and API Token.

### Updating Security and API Credentials

Security updates use dedicated endpoints. For password changes:

```typescript
await fetch("/api/v1/users/me/password/", {
  method: "POST",
  body: JSON.stringify({ old_password, new_password }),
});

```

API tokens and notification preferences follow similar patterns, updating the `currentUserSettings` observable in the MobX store after successful requests.

## How the Settings Data Flow Works

Plane's React frontend implements a centralized state management pattern for settings:

1. **Fetching**: The `useUserSettings` hook calls `GET /api/v1/users/me/settings/` on application load, storing results in the `currentUserSettings` observable.
2. **Storing**: The MobX store in [`apps/web/core/store/user/settings.store.ts`](https://github.com/makeplane/plane/blob/main/apps/web/core/store/user/settings.store.ts) provides reactive data to all UI components, including the workspace drawer and profile modal.
3. **Updating**: Components call `fetchCurrentUserSettings()` after mutations to refresh the observable and trigger re-renders.
4. **Persistence**: The backend processes updates through Django serializers—`InstanceSerializer` for global settings and `WorkspaceSerializer` for workspace data.

Loader components in `apps/web/core/components/ui/loader/settings/*.tsx` display loading states while data fetches.

## Key Source Files for Settings Management

| File Path | Purpose |
|-----------|---------|
| [`apps/web/core/store/user/settings.store.ts`](https://github.com/makeplane/plane/blob/main/apps/web/core/store/user/settings.store.ts) | MobX store managing `currentUserSettings` and fetch/update helpers |
| [`apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx) | UI entry point for workspace settings (gear icon) |
| [`apps/web/core/components/workspace/sidebar/user-menu-root.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/workspace/sidebar/user-menu-root.tsx) | UI entry point for profile settings (avatar menu) |
| [`apps/web/core/components/settings/workspace/sidebar/item-categories.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/settings/workspace/sidebar/item-categories.tsx) | Renders workspace settings navigation tabs |
| [`apps/web/core/components/settings/profile/sidebar/item-categories.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/core/components/settings/profile/sidebar/item-categories.tsx) | Renders profile settings navigation tabs |
| `apps/web/core/components/ui/loader/settings/*.tsx` | Loading components for settings async operations |
| [`packages/types/src/settings.ts`](https://github.com/makeplane/plane/blob/main/packages/types/src/settings.ts) | TypeScript type definitions for settings objects |

## Summary

- Plane uses a **three-layer architecture** separating Instance (global), Workspace (team), and Profile (personal) settings.
- **Instance settings** require God mode access and modify Django configuration directly.
- **Workspace settings** are accessed via the gear icon in [`workspace-menu-header.tsx`](https://github.com/makeplane/plane/blob/main/workspace-menu-header.tsx) and managed through `useUserSettings`.
- **Profile settings** are reached through the user avatar menu and handle credentials via dedicated API endpoints.
- All settings rely on the MobX store in [`settings.store.ts`](https://github.com/makeplane/plane/blob/main/settings.store.ts) to maintain synchronized UI state across the application.

## Frequently Asked Questions

### How do I access God mode to configure instance-wide settings in Plane?

God mode is available exclusively to instance administrators. Navigate to Settings → Instance from the God-mode sidebar, which allows configuration of global email SMTP, authentication providers, and feature flags that apply to the entire Plane deployment.

### Where are user settings stored in the Plane frontend codebase?

User settings are stored in the MobX observable `currentUserSettings` defined in [`apps/web/core/store/user/settings.store.ts`](https://github.com/makeplane/plane/blob/main/apps/web/core/store/user/settings.store.ts). The `useUserSettings` hook provides access to this store throughout the React component tree, ensuring consistent state across the workspace drawer and profile modal.

### What API endpoint updates workspace configuration in Plane?

Workspace settings are updated via `PATCH /api/v1/workspaces/:id/` endpoints. After modifying workspace properties such as webhooks or member policies, the frontend calls `fetchCurrentUserSettings()` to refresh the MobX store and synchronize the UI with the latest server state.

### How do I programmatically update my password or API tokens in Plane?

Profile security settings use dedicated endpoints such as `POST /api/v1/users/me/password/` for password changes. These mutations are handled in the profile settings pages found in `apps/web/core/components/settings/profile/content/pages/`, and automatically refresh the user settings store upon success.