Organizations & Projects

Organizations and Projects provide the foundational structure for organizing your monitoring in 9n9s. Understanding how to effectively use these concepts is crucial for scaling your monitoring as your team and infrastructure grow.

Organizations

An Organization is the top-level container for all your resources in 9n9s. When you sign up for 9n9s, you create your first organization, which serves as the billing entity and primary workspace for your team.

Organization Features

Centralized Management:

Billing & Subscriptions: Each organization has its own subscription plan and billing settings
Team Management: Invite team members and manage their access across all projects
Global Settings: Configure organization-wide notification channels and security policies
Resource Isolation: Keep different teams or business units completely separate

Security & Compliance:

Single Sign-On (SSO): Connect with SAML/OIDC providers for enterprise authentication
Two-Factor Authentication: Enforce 2FA policies across the organization
API Key Management: Generate organization-scoped API keys with configurable permissions
Audit Logging: Track all changes and access across the organization
IP Allowlisting: Restrict access to specific IP addresses or ranges

Customization:

Custom Branding: Upload logos and customize the appearance of status pages
Domain Configuration: Use custom domains for status pages and webhooks
Timezone Settings: Set default timezone for cron schedules and reporting

Creating an Organization

Organizations are created automatically when you sign up for 9n9s. Additional organizations can be created if you need to separate different business units or environments:

# Create a new organization via CLI
9n9s-cli organization create \
  --name "ACME Corp Production" \
  --timezone "America/New_York" \
  --billing-email "[email protected]"

Via API:

curl -X POST https://api.9n9s.com/v1/organizations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corp Production",
    "timezone": "America/New_York",
    "settings": {
      "enforce_2fa": true,
      "allowed_domains": ["acme.com"],
      "data_retention_days": 90
    }
  }'

Organization Settings

General Settings:

Organization Name: Display name used throughout the platform
Default Timezone: Used for cron schedule interpretation and reporting
Data Retention: How long to keep monitor logs and history
Custom Domain: Use your own domain for status pages

Security Settings:

Two-Factor Authentication: Optional, required, or disabled
Session Timeout: Automatic logout after inactivity
API Access: Enable/disable API access for the organization
Webhook Security: Configure webhook signing and IP restrictions

Billing Settings:

Subscription Plan: Free, Professional, or Enterprise
Payment Method: Credit card and billing information
Usage Monitoring: Track usage against plan limits
Invoice History: Access to past invoices and usage reports

Projects

Projects are containers within an organization that group related monitors together. Think of projects as “folders” or “workspaces” for organizing your monitoring based on applications, environments, teams, or any other logical grouping that makes sense for your organization.

Project Structure

Common Organization Patterns:

By Environment:

Organization: ACME Corp
├── Production
├── Staging
├── Development
└── QA Testing

By Application:

Organization: ACME Corp
├── E-commerce Platform
├── Customer Portal
├── Mobile API
└── Analytics System

By Team:

Organization: ACME Corp
├── Backend Services (Backend Team)
├── Frontend Applications (Frontend Team)
├── Data Platform (Data Team)
└── Infrastructure (Platform Team)

By Infrastructure Component:

Organization: ACME Corp
├── Databases
├── APIs & Services
├── Background Jobs
└── External Dependencies

Creating Projects

Via Web Interface:

Navigate to your organization dashboard
Click “Create Project”
Enter project details:
- Name: Descriptive name for the project
- Description: Optional description of what this project monitors
- Default Settings: Timezone, retention, alert preferences
Configure team access and permissions
Click “Create Project”

Via CLI:

# Create a new project
9n9s-cli project create \
  --name "Production API Services" \
  --description "Critical production API endpoints and services" \
  --timezone "UTC" \
  --organization "org_abc123"

# Create with specific settings
9n9s-cli project create \
  --name "Staging Environment" \
  --settings '{
    "default_grace_period": 600,
    "alert_channels": ["slack-staging"],
    "retention_days": 30
  }'

Via API:

curl -X POST https://api.9n9s.com/v1/projects \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Services",
    "description": "Critical production API endpoints and services",
    "organization_id": "org_abc123",
    "settings": {
      "default_timezone": "UTC",
      "retention_days": 90,
      "default_alert_channels": ["chan_pagerduty", "chan_slack"]
    }
  }'

Project Settings

General Configuration:

Project Name: Display name for the project
Description: Detailed description of what the project monitors
Default Timezone: Used for new monitors in this project
Tags: Default tags applied to all monitors in the project

Monitor Defaults:

Grace Period: Default grace period for new heartbeat monitors
Check Frequency: Default frequency for new uptime monitors
Alert Channels: Default notification channels for alerts
Retention Period: How long to keep logs for monitors in this project

Access Control:

Team Members: Users who have access to this project
Permissions: View, Edit, or Admin access for each team member
API Keys: Project-scoped API keys for automation

Team Management

User Roles

9n9s implements a flexible role-based access control (RBAC) system with roles at both organization and project levels:

Organization Roles:

Role	Permissions	Description
Owner	Full access including billing and deletion	Ultimate control over the organization
Admin	All permissions except billing and deletion	Can manage all aspects except financial
Member	Access to assigned projects only	Standard user with project-specific access
Viewer	Read-only access across organization	Can view but not modify anything

Project Roles:

Role	Permissions	Description
Admin	Full control over project and monitors	Can modify project settings and manage access
Editor	Create, modify, and delete monitors and alerts	Standard operational access
Viewer	Read-only access to monitors and logs	Can view but not modify project content

Inviting Team Members

Via Web Interface:

Go to Organization Settings > Team
Click “Invite Member”
Enter email address and select organization role
Choose which projects to grant access to (optional)
Send invitation

Via CLI:

# Invite a new team member
9n9s-cli team invite \
  --email "[email protected]" \
  --role "member" \
  --projects "proj_production,proj_staging" \
  --message "Welcome to our monitoring team!"

Via API:

curl -X POST https://api.9n9s.com/v1/invitations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "organization_role": "member",
    "project_access": [
      {"project_id": "proj_production", "role": "editor"},
      {"project_id": "proj_staging", "role": "admin"}
    ],
    "message": "Welcome to our monitoring team!"
  }'

Managing Permissions

Project Access Management:

# Grant user access to a project
9n9s-cli project add-member \
  --project "proj_production" \
  --user "[email protected]" \
  --role "editor"

# Update user permissions
9n9s-cli project update-member \
  --project "proj_production" \
  --user "[email protected]" \
  --role "admin"

# Remove user from project
9n9s-cli project remove-member \
  --project "proj_production" \
  --user "[email protected]"

Organization Role Management:

# Update organization role
9n9s-cli organization update-member \
  --user "[email protected]" \
  --role "admin"

# Remove from organization
9n9s-cli organization remove-member \
  --user "[email protected]"

Best Practices

Organization Structure

Start Simple, Scale Up:

Begin with a single organization for most use cases
Create additional organizations only when you need complete separation
Use projects to organize within an organization

Security Considerations:

Enable 2FA enforcement in production organizations
Use SSO integration for larger teams
Implement IP allowlisting for sensitive environments
Regularly audit team access and permissions

Billing Optimization:

Monitor usage across projects to understand costs
Use tags to track usage by team or application
Set up billing alerts to avoid surprises

Project Organization

Logical Grouping:

Group monitors that are managed by the same team
Separate environments (production, staging, development)
Group by service criticality for different alert routing

Naming Conventions:

Use clear, descriptive project names
Include environment information where relevant
Consider using prefixes for organization: prod-, staging-, dev-

Access Management:

Grant minimum necessary permissions
Use project-level access rather than organization-wide when possible
Regularly review and update access permissions

Team Collaboration

Clear Responsibilities:

Document who owns which projects and monitors
Use tags to indicate ownership and responsibility
Set up appropriate alert routing based on ownership

Communication:

Use descriptive monitor names and descriptions
Document monitoring strategies and runbooks
Share knowledge about critical monitors and their context

Automation and API Usage

Infrastructure as Code

Terraform Example:

# Define organization
data "nines_organization" "main" {
  name = "ACME Corp"
}

# Create projects
resource "nines_project" "production" {
  name = "Production Services"
  organization_id = data.nines_organization.main.id

  settings = {
    default_timezone = "UTC"
    retention_days = 90
    default_grace_period = 300
  }
}

resource "nines_project" "staging" {
  name = "Staging Environment"
  organization_id = data.nines_organization.main.id

  settings = {
    default_timezone = "UTC"
    retention_days = 30
    default_grace_period = 600
  }
}

# Manage team access
resource "nines_project_member" "jane_production" {
  project_id = nines_project.production.id
  user_email = "[email protected]"
  role = "editor"
}

Programmatic Management

Bulk Operations:

# Python script to create projects for multiple environments
import requests

API_KEY = "your-api-key"
ORG_ID = "org_abc123"

environments = ["production", "staging", "development", "qa"]

for env in environments:
    project_data = {
        "name": f"{env.title()} Environment",
        "description": f"Monitoring for {env} environment",
        "organization_id": ORG_ID,
        "settings": {
            "default_timezone": "UTC",
            "retention_days": 90 if env == "production" else 30
        }
    }

    response = requests.post(
        "https://api.9n9s.com/v1/projects",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=project_data
    )

    if response.status_code == 201:
        print(f"Created project: {env}")
    else:
        print(f"Failed to create {env}: {response.text}")

Monitoring Organization Health

API Usage Monitoring:

# Check organization usage
curl -H "Authorization: Bearer $API_KEY" \
  https://api.9n9s.com/v1/organizations/org_abc123/usage

# List all projects and their monitor counts
curl -H "Authorization: Bearer $API_KEY" \
  https://api.9n9s.com/v1/projects?include=monitor_counts

Troubleshooting

Common Issues

Permission Denied Errors:

Check user has appropriate role for the operation
Verify project access for project-specific operations
Ensure API key has required permissions

Project Creation Failures:

Check organization limits on number of projects
Verify unique project names within organization
Ensure valid timezone specification

Team Invitation Issues:

Verify email address is correct
Check if user already exists in organization
Ensure sender has permission to invite users

Getting Help

Documentation:

Support:

Email: [email protected]
Community: GitHub Discussions
Enterprise: Dedicated support for enterprise customers

Organizations and Projects provide the foundation for scaling your monitoring effectively. By thoughtfully organizing your monitors and managing team access, you can create a monitoring setup that grows with your organization while maintaining security and clarity.