Creating Organizations

Learn how to create and configure organizations for isolated workspaces.

Prerequisites

Before creating an organization:

• Active Mesrai account
• Verified email address
• Subscription plan (Starter or higher)

Creating Your First Organization

Step 1: Access Organization Creator

1. Log in to your Mesrai dashboard
2. Click Add Organization in the sidebar
3. Or go to Settings → Organizations → Create New

Step 2: Basic Information

Provide organization details:

Organization Name (required)

• Unique, descriptive name
• 3-50 characters
• Letters, numbers, hyphens allowed
• Examples: “acme-corp”, “engineering-team”, “client-alpha”

Display Name (optional)

• Human-readable name
• Examples: “ACME Corporation”, “Engineering Team”, “Client Alpha”

Organization Slug (auto-generated)

• URL-safe identifier
• Used in URLs: app.mesrai.com/org/{slug}
• Cannot be changed after creation

Description (optional)

• Brief purpose or scope
• Visible to all members
• Max 500 characters

Example:

Name: acme-engineering
Display Name: ACME Engineering
Slug: acme-engineering
Description: Engineering department for ACME Corporation

Step 3: Organization Settings

Configure initial preferences:

Default Member Role

• Owner (full control)
• Admin (management access)
• Member (read access)

Visibility

• Private (invite-only)
• Internal (company members)
• Public (discoverable)

Notifications

• Email notifications
• Slack integration
• In-app alerts

Step 4: Invite Initial Members

Add team members:

1. Enter email addresses (comma-separated)
2. Assign roles per member
3. Add optional welcome message
4. Send invitations

Can be skipped and done later.

Step 5: Connect Integrations

Set up integrations:

GitHub App

1. Click “Connect GitHub”
2. Authorize Mesrai GitHub App
3. Select organization
4. Choose repositories

Learn more about GitHub integration →

Other Integrations

• Slack notifications
• Jira issue tracking
• PagerDuty alerts

Step 6: Configure Billing

Set up billing for the organization:

1. Choose subscription plan
2. Add payment method
3. Configure usage limits
4. Set billing notifications

Learn more about billing →

Step 7: Review and Create

Review configuration:

• Organization name and details
• Member invitations
• Connected integrations
• Billing setup
• Settings

Click Create Organization to finish.

Organization Configuration

Profile Settings

Organization Logo

• Upload custom logo
• Recommended: 512x512 px
• Formats: PNG, JPG, SVG
• Max size: 2 MB

Organization Details

name: acme-engineering
display_name: ACME Engineering
website: https://acme.com
industry: Software Development
size: 50-100 employees

Access Control

Single Sign-On (SSO)

sso:
  enabled: true
  provider: okta
  domain: acme.okta.com
  enforce: true  # Require SSO for all members

Domain Verification Verify email domains:

Verified Domains:
  - acme.com ✓
  - acme.io ✓

Auto-join: Members with verified domains auto-join

Security Settings

Two-Factor Authentication

• Require 2FA for all members
• Grace period: 7 days
• Enforcement level: Strict/Flexible

API Access

api:
  enabled: true
  rate_limit: 1000/hour
  ip_whitelist:
    - 203.0.113.0/24
    - 198.51.100.0/24

Audit Logging

• Log all actions
• Retention: 90 days (Pro), 1 year (Enterprise)
• Export to external SIEM

Advanced Configuration

Custom Branding

Personalize organization appearance:

branding:
  primary_color: "#3B82F6"
  logo_url: "https://cdn.acme.com/logo.svg"
  favicon_url: "https://cdn.acme.com/favicon.ico"
  custom_domain: "reviews.acme.com"

Webhook Configuration

Set up organization-wide webhooks:

webhooks:
  - url: "https://api.acme.com/mesrai/events"
    events:
      - review.completed
      - member.added
      - repository.connected
    secret: "whsec_xxxxxxxxxxxxx"

Integration Presets

Configure default integrations for all teams:

integrations:
  slack:
    workspace: acme-team
    default_channel: "#code-reviews"
 
  jira:
    site: acme.atlassian.net
    project_key: ENG

Organization Templates

Use templates for common setups:

Startup Template

template: startup
members: 5-10
teams: 1-2
repositories: 5-15
features:
  - basic_analytics
  - email_notifications
  - github_integration

Enterprise Template

template: enterprise
members: 100+
teams: 10+
repositories: 50+
features:
  - sso
  - advanced_analytics
  - audit_logging
  - custom_branding
  - dedicated_support

Agency Template

template: agency
organizations: multiple (one per client)
isolation: strict
billing: per_organization
features:
  - client_branding
  - usage_tracking
  - white_label

Migrating from Personal Account

Convert personal account to organization:

Migration Steps

1. Backup Data

   • Export repositories list
   • Save API keys
   • Document integrations

2. Create Organization

   • New organization with desired name
   • Transfer repositories
   • Invite team members

3. Update Integrations

   • Reconnect GitHub App
   • Update webhooks
   • Reconfigure Slack

4. Transfer Billing

   • Move subscription to organization
   • Update payment method
   • Cancel personal subscription

What Gets Transferred

Multi-Organization Setup

Managing multiple organizations:

Organization Switcher

Quick switch between organizations:

1. Click organization name in sidebar
2. Select from dropdown
3. Context switches instantly

Keyboard shortcut: Cmd/Ctrl + K → type organization name

Centralized Billing

Enterprise feature - single billing for all organizations:

billing_group:
  name: "ACME Corporation"
  organizations:
    - acme-engineering
    - acme-product
    - acme-data
  billing: consolidated
  payment_method: corporate_card

Cross-Organization Permissions

Grant users access to multiple organizations:

john@acme.com
  ├── acme-engineering (Owner)
  ├── acme-product (Admin)
  └── acme-data (Member)

Troubleshooting

Organization Name Already Taken

Problem: “Organization name is unavailable”

Solutions:

1. Try variations: add hyphens, numbers
2. Use display name for branding
3. Contact support if you own the trademark

Can’t Create Organization

Problem: “You’ve reached the organization limit”

Solutions:

1. Check your subscription plan limits
2. Upgrade to higher tier
3. Delete unused organizations
4. Contact sales for enterprise pricing

GitHub App Connection Failed

Problem: Can’t connect GitHub to organization

Solutions:

1. Verify GitHub organization admin access
2. Check Mesrai is authorized in GitHub
3. Re-authorize GitHub App
4. Ensure correct GitHub organization selected

Learn more about GitHub troubleshooting →

Members Can’t Join Organization

Problem: Invited members can’t see organization

Solutions:

1. Verify invitation was sent and accepted
2. Check email domain restrictions
3. Ensure member has verified email
4. Check organization visibility settings

Best Practices

1. Clear Naming Convention

Use consistent naming:

• Client-based: client-acme, client-techcorp
• Department-based: engineering, product, data
• Project-based: project-alpha, project-beta

2. Proper Isolation

Separate organizations for:

• Different clients (agencies)
• Different legal entities
• Independent billing requirements
• Strict data isolation needs

3. Documentation

Document organization purpose:

• Who should join
• What repositories to connect
• Billing responsibility
• Primary contact

4. Regular Audits

Quarterly review:

• Remove inactive members
• Audit repository access
• Review billing and usage
• Update settings

API Reference

Create organizations programmatically:

Create Organization

POST /v1/organizations
{
  "name": "acme-engineering",
  "displayName": "ACME Engineering",
  "description": "Engineering department",
  "settings": {
    "defaultRole": "MEMBER",
    "visibility": "PRIVATE"
  }
}

Response:

{
  "id": "org_abc123",
  "name": "acme-engineering",
  "displayName": "ACME Engineering",
  "slug": "acme-engineering",
  "createdAt": "2025-01-15T10:30:00Z",
  "owner": "user@example.com"
}

Update Organization

PATCH /v1/organizations/{orgId}
{
  "displayName": "ACME Engineering Team",
  "description": "Updated description"
}

Delete Organization

DELETE /v1/organizations/{orgId}

Warning: Irreversible action. All data will be deleted.

Next Steps

• Invite Members
• Configure Settings
• Set Up Billing
• Connect GitHub
• Create Teams

Support

Need help creating organizations?

• Discord Community
• Email Support
• Schedule Demo