Instance Administration

Instance administrators have full control over your self-hosted Plane deployment. This guide covers instance admin setup, permissions, and management capabilities.

What is an Instance Admin?

Instance admins are super users who can:

Configure instance-wide settings
Manage authentication providers
Control user signup and workspace creation
Add and remove other instance admins
Monitor instance health and usage
Manage integrations and API keys

Instance admin access is separate from workspace permissions. Instance admins can manage the entire Plane instance, not just individual workspaces.

First-Time Setup

When you deploy Plane for the first time, you’ll need to create the first instance admin.

Create First Admin via Web Interface

Access Admin Panel

Navigate to your Plane instance at the configured URL:

https://plane.example.com/admin

You’ll be redirected to the admin signup page.

Complete Signup Form

Fill in the required information:

Email: Your admin email address
Password: Strong password (minimum strength score: 3/4)
First Name: Your first name
Last Name: Your last name (optional)
Company Name: Your organization name
Telemetry: Enable/disable usage telemetry

Password strength is validated using zxcvbn. Weak passwords will be rejected.

Submit

Click “Create Admin Account” to complete setup.This will:

Create your user account
Register you as the first instance admin
Mark the instance as setup complete
Log you into the admin panel

Create Admin via Command Line

If you need to create an instance admin from the command line:

Docker Compose
Kubernetes

# Enter the API container
docker exec -it api /bin/bash

# Create instance admin
python manage.py create_instance_admin [email protected]

Important: The user must already exist. If not, create the user first:

# Create user account
python manage.py createsuperuser --email [email protected]

# Then create instance admin
python manage.py create_instance_admin [email protected]

# Get API pod name
kubectl get pods -n plane -l app=plane-api

# Execute command in pod
kubectl exec -n plane -it <api-pod-name> -- \
  python manage.py create_instance_admin [email protected]

If user doesn’t exist:

# Create user first
kubectl exec -n plane -it <api-pod-name> -- \
  python manage.py createsuperuser --email [email protected]

# Then create instance admin
kubectl exec -n plane -it <api-pod-name> -- \
  python manage.py create_instance_admin [email protected]

The create_instance_admin command is located at: plane/db/management/commands/create_instance_admin.py

Accessing the Admin Panel

Navigate to:

https://plane.example.com/admin

Admin Panel Sections

Once logged in, you’ll have access to:

General Settings

Configure instance name, telemetry, and basic settings

Authentication

Manage OAuth providers, signup settings, and login methods

Email

Configure SMTP settings for email notifications

AI & Integrations

Set up LLM, Unsplash, Slack, and other integrations

Image Settings

Configure file upload limits and storage

Instance Admins

Add or remove instance administrators

Managing Instance Admins

Adding Additional Admins

Via Admin Panel
Via CLI
Via API

Navigate to Admins

In the admin panel, go to Instance Admins section.

Add Admin

Click “Add Admin” and enter the user’s email address.

The user must already have an account on the instance. If not, invite them as a regular user first.

Set Role

Select the admin role:

Admin (20): Full instance administration rights

Currently, only one role level exists, but the architecture supports future role expansion.

Confirm

Click “Add” to grant instance admin privileges.

# Docker Compose
docker exec -it api python manage.py create_instance_admin [email protected]

# Kubernetes
kubectl exec -n plane -it <api-pod-name> -- \
  python manage.py create_instance_admin [email protected]

curl -X POST https://plane.example.com/api/instances/admins/ \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": 20
  }'

Removing Admins

Via Admin Panel
Via API

Go to Instance Admins section
Find the admin to remove
Click the Remove button
Confirm the action

curl -X DELETE https://plane.example.com/api/instances/admins/<admin-id>/ \
  -H "Authorization: Bearer <admin-token>"

Ensure at least one instance admin remains. You cannot remove the last admin.

Viewing All Admins

# Via API
curl -X GET https://plane.example.com/api/instances/admins/ \
  -H "Authorization: Bearer <admin-token>"

Response:

[
  {
    "id": "uuid",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    },
    "role": 20,
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Instance Configuration

General Settings

Configure basic instance information:

Instance Name: Your Organization
Instance ID: auto-generated-uuid
Version: Current version (e.g., v0.23.0)
Edition: PLANE_COMMUNITY

Telemetry Settings:

Enable Telemetry: Send anonymous usage data to help improve Plane
Support Required: Allow Plane team to provide assistance

Authentication Settings

Control how users authenticate:

User Signup: Enabled/Disabled
Email/Password: Enabled/Disabled
Magic Link Login: Enabled/Disabled

When signup is disabled, only admins can invite new users.

OAuth Providers

Configure social authentication:

Google OAuth

Enable Google OAuth
Add Client ID and Secret from Google Cloud Console
Configure redirect URI: https://plane.example.com/auth/google/callback/
Save settings

GitHub OAuth

Enable GitHub OAuth
Add Client ID and Secret from GitHub Developer Settings
Configure callback URL: https://plane.example.com/auth/github/callback/
Save settings

GitLab OAuth

Enable GitLab OAuth
Add Client ID and Secret from GitLab Application settings
Configure redirect URI: https://plane.example.com/auth/gitlab/callback/
Set GitLab host (for self-hosted GitLab)
Save settings

Workspace Creation

Disable Workspace Creation: No

Set to “Yes” to restrict workspace creation to admins only.

Email Configuration

Set up SMTP for email notifications:

SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Username: [email protected]
SMTP Password: ••••••••
From Email: [email protected]
Use TLS: Yes
Use SSL: No

Test email configuration by sending a test email from the admin panel.

Integration Settings

AI Features

LLM Provider: OpenAI
API Key: sk-••••••••••••••••
Model: gpt-4

Enables AI-powered features like:

Smart issue suggestions
Auto-completion
Content generation

Unsplash Integration

Unsplash Access Key: your-access-key

Enables cover image selection from Unsplash.

Slack Integration

Slack Client ID: your-client-id
Slack Client Secret: your-client-secret

Enables Slack notifications and integrations.

File Upload Settings

Maximum File Size: 5 MB (5242880 bytes)

Adjust based on your storage capacity and user needs.

Instance Information API

Retrieve instance configuration programmatically:

curl -X GET https://plane.example.com/api/instances/

Response:

{
  "config": {
    "enable_signup": true,
    "is_workspace_creation_disabled": false,
    "is_google_enabled": true,
    "is_github_enabled": false,
    "is_gitlab_enabled": false,
    "is_magic_login_enabled": true,
    "is_email_password_enabled": true,
    "is_smtp_configured": true,
    "has_unsplash_configured": true,
    "has_llm_configured": false,
    "file_size_limit": 5242880,
    "admin_base_url": "https://plane.example.com/admin",
    "space_base_url": "https://plane.example.com/spaces",
    "app_base_url": "https://plane.example.com"
  },
  "instance": {
    "instance_name": "Your Organization",
    "instance_id": "uuid",
    "current_version": "v0.23.0",
    "latest_version": "v0.23.0",
    "edition": "PLANE_COMMUNITY",
    "is_setup_done": true,
    "is_telemetry_enabled": true,
    "workspaces_exist": true
  }
}

Admin Session Management

Check Admin Session

curl -X GET https://plane.example.com/api/instances/admins/session/ \
  --cookie "sessionid=<session-cookie>"

Response:

{
  "is_authenticated": true,
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "avatar": "https://...",
    "is_instance_admin": true
  }
}

Sign Out

Navigate to:

https://plane.example.com/admin/sign-out

Or via API:

curl -X POST https://plane.example.com/api/instances/admins/sign-out/ \
  --cookie "sessionid=<session-cookie>"

Permission Model

Instance admin permissions are enforced through the InstanceAdminPermission class:

from plane.license.api.permissions import InstanceAdminPermission

class ProtectedView(APIView):
    permission_classes = [InstanceAdminPermission]

This ensures only users with InstanceAdmin role can access protected endpoints.

Admin Database Model

Instance admins are stored in the instance_admins table:

class InstanceAdmin(BaseModel):
    user = ForeignKey(User, on_delete=SET_NULL)
    instance = ForeignKey(Instance, on_delete=CASCADE)
    role = PositiveIntegerField(choices=ROLE_CHOICES, default=20)
    is_verified = BooleanField(default=False)

    class Meta:
        unique_together = ["instance", "user"]

Fields:

user: Link to User model
instance: Link to Instance model
role: Admin role (currently only 20 = Admin)
is_verified: Verification status (future use)

Security Best Practices

Use Strong Passwords

Require minimum password strength score of 3/4 using zxcvbn validation.

Limit Admin Access

Only grant instance admin privileges to trusted team members who need full access.

Enable 2FA

If your authentication provider supports it, enable two-factor authentication for admin accounts.

Regular Audits

Periodically review the list of instance admins and remove users who no longer need access.

Monitor Admin Actions

Check admin panel logs regularly:

docker compose logs api | grep "instance_admin"

Secure Environment Variables

Protect your .env file and never commit credentials to version control.

Troubleshooting

Cannot Access Admin Panel

Issue: 401 Unauthorized or redirect loop Solutions:

Verify you’re using an instance admin account
Check session cookie is present
Clear browser cookies and sign in again

Verify instance is properly configured:

docker compose logs api | grep "Instance registered"

Admin Creation Fails

Issue: User with the provided email does not exist Solution: Create the user account first:

docker exec -it api python manage.py createsuperuser --email [email protected]
docker exec -it api python manage.py create_instance_admin [email protected]

Multiple Admins with Same Email

Issue: UNIQUE constraint failed: instance_admins.instance_id, instance_admins.user_id Solution: The user is already an instance admin. Check existing admins:

docker exec -it api python manage.py shell -c \
  "from plane.license.models import InstanceAdmin; print(InstanceAdmin.objects.all())"

Instance Not Setup

Issue: Instance is not registered yet Solution: Register the instance:

docker exec -it api python manage.py register_instance

Password Too Weak Error

Issue: PASSWORD_TOO_WEAK error during admin signup Solution: Use a stronger password. Requirements:

Minimum length: 8 characters
zxcvbn strength score: ≥3
Mix of uppercase, lowercase, numbers, and symbols recommended

API Endpoints Reference

Endpoint	Method	Description	Auth Required
`/api/instances/`	GET	Get instance info	No
`/api/instances/`	PATCH	Update instance settings	Instance Admin
`/api/instances/admins/`	GET	List all admins	Instance Admin
`/api/instances/admins/`	POST	Add new admin	Instance Admin
`/api/instances/admins/<id>/`	DELETE	Remove admin	Instance Admin
`/api/instances/admins/me/`	GET	Get current admin user	Instance Admin
`/api/instances/admins/session/`	GET	Check admin session	No
`/admin/sign-up/`	POST	Create first admin	No (first time only)
`/admin/sign-in/`	POST	Admin sign in	No
`/admin/sign-out/`	POST	Admin sign out	Instance Admin

Get Started

Core Features

Self-Hosting

Development

​What is an Instance Admin?

​First-Time Setup

​Create First Admin via Web Interface

​Create Admin via Command Line

​Accessing the Admin Panel

​Admin Sign In

​Admin Panel Sections

General Settings

Authentication

Email

AI & Integrations

Image Settings

Instance Admins

​Managing Instance Admins

​Adding Additional Admins

​Removing Admins

​Viewing All Admins

​Instance Configuration

​General Settings

​Authentication Settings

​Signup & Login Methods

​OAuth Providers

​Workspace Creation

​Email Configuration

​Integration Settings

​AI Features

​Unsplash Integration

​Slack Integration

​File Upload Settings

​Instance Information API

​Admin Session Management

​Check Admin Session

​Sign Out

​Permission Model

​Admin Database Model

​Security Best Practices

​Troubleshooting

​Cannot Access Admin Panel

​Admin Creation Fails

​Multiple Admins with Same Email

​Instance Not Setup

​Password Too Weak Error

​API Endpoints Reference

​Next Steps

Configuration

Backup & Recovery

Build docs developers (and LLMs) love

What is an Instance Admin?

First-Time Setup

Create First Admin via Web Interface

Create Admin via Command Line

Accessing the Admin Panel

Admin Sign In

Admin Panel Sections

Managing Instance Admins

Adding Additional Admins

Removing Admins

Viewing All Admins

Instance Configuration

General Settings

Authentication Settings

Signup & Login Methods

OAuth Providers

Workspace Creation

Email Configuration

Integration Settings

AI Features

Unsplash Integration

Slack Integration

File Upload Settings

Instance Information API

Admin Session Management

Check Admin Session

Sign Out

Permission Model

Admin Database Model

Security Best Practices

Troubleshooting

Cannot Access Admin Panel

Admin Creation Fails

Multiple Admins with Same Email

Instance Not Setup

Password Too Weak Error

API Endpoints Reference

Next Steps