API Keys

API keys provide programmatic access to 9n9s for automation, integrations, and third-party applications. This guide covers creating, managing, and securing API keys effectively.

API Key Types

Personal Access Tokens

Purpose: User-specific API access that inherits the user’s permissions.

Use Cases:

Personal automation scripts
Development and testing
Individual CI/CD pipelines
Command-line tool access

Characteristics:

personal_access_token:
    scope: "user_permissions"
    inheritance: "user_role_permissions"
    expiration: "configurable (max 1 year)"
    rate_limits: "user_tier_limits"
    audit_trail: "linked_to_user"

Service Account Keys

Purpose: Application-specific access with limited, defined permissions.

Use Cases:

Production automation
Team CI/CD pipelines
Third-party integrations
Monitoring tools

Characteristics:

service_account_key:
    scope: "limited_permissions"
    inheritance: "explicit_permissions_only"
    expiration: "required (max 90 days)"
    rate_limits: "service_tier_limits"
    audit_trail: "service_account_activity"

Integration Keys

Purpose: Specialized keys for specific integrations and external services.

Use Cases:

Webhook endpoints
SSO integrations
Third-party monitoring platforms
Custom applications

Characteristics:

integration_key:
    scope: "integration_specific"
    inheritance: "predefined_integration_permissions"
    expiration: "integration_dependent"
    rate_limits: "integration_specific"
    audit_trail: "integration_activity"

Creating API Keys

Web Interface

Create Personal Access Token:

Navigate to Account → API Keys
Click “Create New Key”
Select “Personal Access Token”
Enter a descriptive name
Set expiration date (optional)
Choose permissions (defaults to your current permissions)
Click “Generate Key”

Create Service Account Key:

Navigate to Account → API Keys
Click “Create New Key”
Select “Service Account”
Enter service name and description
Select specific permissions needed
Set mandatory expiration date (max 90 days)
Configure IP restrictions (optional)
Click “Generate Key”

CLI Interface

Personal Access Token:

# Create personal access token
9n9s-cli auth create-token \
  --name "Personal Automation" \
  --expires "2024-12-31" \
  --permissions "monitor:read,monitor:write"

# Create token with full user permissions
9n9s-cli auth create-token \
  --name "Development Work" \
  --expires "2024-06-30" \
  --inherit-permissions

Service Account Key:

# Create service account with limited permissions
9n9s-cli auth create-service-account \
  --name "CI/CD Pipeline" \
  --description "GitHub Actions monitoring integration" \
  --permissions "monitor:read,monitor:create,alert:read" \
  --expires "2024-03-15" \
  --ip-allowlist "54.239.123.0/24"

# Create service account for specific team
9n9s-cli auth create-service-account \
  --name "Backend Team Automation" \
  --team "backend-team" \
  --permissions "monitor:read,monitor:write,dashboard:read" \
  --expires "2024-04-01"

API Creation

Create via API:

# Create personal access token
curl -X POST https://api.9n9s.com/v1/auth/tokens \
  -H "Authorization: Bearer $CURRENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Automation Script",
    "type": "personal_access_token",
    "expires_at": "2024-12-31T23:59:59Z",
    "permissions": ["monitor:read", "monitor:write"]
  }'

# Create service account
curl -X POST https://api.9n9s.com/v1/auth/service-accounts \
  -H "Authorization: Bearer $CURRENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Monitoring",
    "description": "Automated production monitoring",
    "permissions": ["monitor:read", "alert:read"],
    "expires_at": "2024-03-15T23:59:59Z",
    "ip_allowlist": ["192.168.1.0/24"]
  }'

Permissions and Scopes

Permission Types

Monitor Permissions:

monitor_permissions:
    "monitor:read": "View monitor configurations and status"
    "monitor:write": "Create and update monitors"
    "monitor:delete": "Delete monitors"
    "monitor:pause": "Pause and resume monitors"
    "monitor:export": "Export monitor data"

Dashboard Permissions:

dashboard_permissions:
    "dashboard:read": "View dashboards"
    "dashboard:write": "Create and update dashboards"
    "dashboard:delete": "Delete dashboards"
    "dashboard:share": "Share dashboards with others"
    "dashboard:embed": "Create embeddable dashboard links"

Alert Permissions:

alert_permissions:
    "alert:read": "View alert configurations and history"
    "alert:write": "Configure alert rules and channels"
    "alert:acknowledge": "Acknowledge and resolve alerts"
    "alert:escalate": "Escalate alerts to higher levels"

Administrative Permissions:

admin_permissions:
    "user:read": "View user information"
    "user:write": "Manage user accounts"
    "team:read": "View team information"
    "team:write": "Manage team memberships"
    "billing:read": "View billing information"
    "audit:read": "Access audit logs"

Scope Patterns

Least Privilege Examples:

# CI/CD Pipeline - minimal required permissions
ci_cd_permissions:
    - "monitor:read"
    - "monitor:create"
    - "monitor:update"
    # Exclude: monitor:delete, admin permissions

# Monitoring Dashboard - read-only access
dashboard_permissions:
    - "monitor:read"
    - "dashboard:read"
    - "alert:read"
    # Exclude: write permissions

# Alert Management - notification system
alert_system_permissions:
    - "alert:read"
    - "alert:acknowledge"
    - "monitor:read"
    # Exclude: configuration changes

Team-Scoped Permissions:

# Permissions can be scoped to specific teams
team_scoped_key:
    team: "backend-team"
    permissions:
        - "monitor:read"
        - "monitor:write"
    # Only applies to backend-team resources

Security Features

Expiration Management

Automatic Expiration:

expiration_policies:
    personal_access_tokens:
        default_expiry: "1 year"
        max_expiry: "1 year"
        warning_threshold: "30 days"

    service_accounts:
        default_expiry: "90 days"
        max_expiry: "90 days"
        warning_threshold: "7 days"

    integration_keys:
        default_expiry: "1 year"
        max_expiry: "2 years"
        warning_threshold: "14 days"

Expiration Notifications:

# Get expiring keys report
9n9s-cli auth expiring-keys --days 30

# Set up expiration alerts
9n9s-cli auth set-expiration-alerts \
  --email [email protected] \
  --days-before 7,1

# Auto-rotate service account keys
9n9s-cli auth auto-rotate \
  --service-account "production-monitoring" \
  --rotate-before-days 7

IP Allowlisting

Restrict Access by IP:

ip_restrictions:
    enabled: true
    rules:
        - cidr: "192.168.1.0/24"
          description: "Office network"
        - cidr: "10.0.0.0/8"
          description: "VPN users"
        - ip: "54.239.123.456"
          description: "CI/CD server"

    default_action: "deny"
    logging: true

Configure IP Restrictions:

# Add IP restriction to existing key
9n9s-cli auth update-key key_abc123 \
  --add-ip "192.168.1.100" \
  --add-cidr "10.0.0.0/8"

# Create key with IP restrictions
9n9s-cli auth create-service-account \
  --name "Restricted Service" \
  --ip-allowlist "192.168.1.0/24,10.0.0.0/8" \
  --permissions "monitor:read"

Rate Limiting

API Rate Limits by Key Type:

rate_limits:
    personal_access_token:
        requests_per_minute: 100
        requests_per_hour: 5000
        requests_per_day: 50000

    service_account:
        requests_per_minute: 200
        requests_per_hour: 10000
        requests_per_day: 100000

    integration_key:
        requests_per_minute: 50
        requests_per_hour: 2000
        requests_per_day: 20000

Rate Limit Headers:

# API responses include rate limit information
curl -H "Authorization: Bearer $API_KEY" \
  https://api.9n9s.com/v1/monitors

# Response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1642694400

Key Management

Key Rotation

Manual Rotation:

# Rotate existing key
9n9s-cli auth rotate-key key_abc123

# Rotate with overlap period
9n9s-cli auth rotate-key key_abc123 \
  --overlap-days 7 \
  --notify [email protected]

# Generate new key for service account
9n9s-cli auth service-account rotate "ci-cd-pipeline"

Automated Rotation:

# Configure automatic rotation
auto_rotation:
    enabled: true
    service_accounts:
        - name: "production-monitoring"
          rotate_before_expiry: "7 days"
          notify_channels: ["slack-ops", "email-devops"]

        - name: "ci-cd-pipeline"
          rotate_before_expiry: "3 days"
          update_webhook: "https://ci.company.com/update-key"

Rotation Workflow:

rotation_process:
    1: "Generate new key with same permissions"
    2: "Notify administrators of new key"
    3: "Maintain old key for overlap period"
    4: "Deactivate old key after overlap"
    5: "Log rotation event for audit"

Key Deactivation

Temporary Deactivation:

# Temporarily disable key
9n9s-cli auth disable-key key_abc123 \
  --reason "Security investigation"

# Re-enable key
9n9s-cli auth enable-key key_abc123

# Disable with automatic re-enable
9n9s-cli auth disable-key key_abc123 \
  --duration "2 hours" \
  --reason "Maintenance window"

Permanent Revocation:

# Permanently revoke key
9n9s-cli auth revoke-key key_abc123 \
  --reason "Compromised credentials"

# Revoke all keys for user
9n9s-cli auth revoke-user-keys [email protected] \
  --exclude key_def456

# Emergency revocation
9n9s-cli auth emergency-revoke \
  --service-account "compromised-service" \
  --notify-security

Monitoring and Auditing

Usage Monitoring

API Key Activity:

# View key usage statistics
9n9s-cli auth key-usage key_abc123 \
  --start-date "2024-01-01" \
  --end-date "2024-01-31"

# Monitor unusual activity
9n9s-cli auth audit-keys \
  --unusual-activity \
  --threshold-multiplier 3

# Generate usage report
9n9s-cli auth usage-report \
  --format csv \
  --include-all-keys

Activity Patterns:

monitoring_metrics:
    request_volume:
        - requests_per_hour
        - peak_usage_times
        - geographic_distribution

    usage_patterns:
        - endpoint_popularity
        - error_rates
        - response_times

    security_events:
        - failed_authentication
        - ip_violations
        - rate_limit_exceeded

Audit Logging

Audit Events:

{
    "timestamp": "2024-01-15T10:30:00Z",
    "event_type": "api_key_created",
    "actor": {
        "user_id": "user_123",
        "email": "[email protected]",
        "ip_address": "192.168.1.100"
    },
    "target": {
        "key_id": "key_abc123",
        "key_name": "CI/CD Pipeline",
        "key_type": "service_account"
    },
    "details": {
        "permissions": ["monitor:read", "monitor:write"],
        "expires_at": "2024-04-15T00:00:00Z",
        "ip_restrictions": ["54.239.123.0/24"]
    }
}

Audit Queries:

# Search audit logs for key events
9n9s-cli audit search \
  --event-type "api_key_*" \
  --start-date "2024-01-01"

# Find suspicious key usage
9n9s-cli audit search \
  --event-type "api_request" \
  --filter "source_ip NOT IN allowlist"

# Generate security report
9n9s-cli audit security-report \
  --focus "api_keys" \
  --format pdf

Integration Examples

CI/CD Integration

GitHub Actions:

name: Update Monitoring
on:
    push:
        branches: [main]

jobs:
    update-monitors:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3

            - name: Configure 9n9s CLI
              env:
                  NINE_NS_API_KEY: ${{ secrets.NINE_NS_API_KEY }}
              run: |
                  echo "$NINE_NS_API_KEY" | 9n9s-cli auth login --stdin

            - name: Deploy monitoring configuration
              run: |
                  9n9s-cli config apply --file monitors.yml

Jenkins Pipeline:

pipeline {
    agent any

    environment {
        NINE_NS_API_KEY = credentials('nine-ns-api-key')
    }

    stages {
        stage('Update Monitors') {
            steps {
                script {
                    sh '''
                        9n9s-cli auth login --api-key $NINE_NS_API_KEY
                        9n9s-cli monitors sync --config monitoring.json
                    '''
                }
            }
        }
    }
}

Infrastructure as Code

Terraform Integration:

# Configure 9n9s provider
terraform {
  required_providers {
    nine-ns = {
      source  = "9n9s/nine-ns"
      version = "~> 1.0"
    }
  }
}

provider "nine-ns" {
  api_key = var.nine_ns_api_key
}

# Create service account for terraform
resource "nine_ns_service_account" "terraform" {
  name        = "terraform-automation"
  description = "Terraform infrastructure monitoring"

  permissions = [
    "monitor:read",
    "monitor:write",
    "dashboard:read"
  ]

  expires_at = "2024-12-31T23:59:59Z"

  ip_allowlist = [
    "192.168.1.0/24"
  ]
}

Ansible Playbook:

---
- name: Configure 9n9s Monitoring
  hosts: localhost
  vars:
      nine_ns_api_key: "{{ vault_nine_ns_api_key }}"

  tasks:
      - name: Create monitoring configuration
        uri:
            url: "https://api.9n9s.com/v1/monitors"
            method: POST
            headers:
                Authorization: "Bearer {{ nine_ns_api_key }}"
                Content-Type: "application/json"
            body_format: json
            body:
                name: "{{ service_name }} Health Check"
                type: "uptime"
                url: "{{ service_url }}/health"
                frequency: "1m"

Best Practices

Security Best Practices

Key Management:

Principle of Least Privilege: Grant only required permissions
Regular Rotation: Rotate keys every 90 days or less
Secure Storage: Use secure credential management systems
Monitoring: Track key usage for anomalies
Immediate Revocation: Revoke compromised keys immediately

Development Practices:

security_practices:
    development:
        - use_environment_variables
        - never_commit_keys_to_version_control
        - use_different_keys_per_environment
        - implement_key_rotation_in_deployment

    production:
        - use_service_accounts_not_personal_tokens
        - implement_ip_allowlisting
        - monitor_key_usage_patterns
        - set_up_expiration_alerts

    operations:
        - regular_access_reviews
        - audit_key_permissions
        - document_key_purposes
        - maintain_key_inventory

Operational Best Practices

Key Organization:

naming_conventions:
    format: "[environment]-[service]-[purpose]"
    examples:
        - "prod-api-monitoring"
        - "staging-ci-deployment"
        - "dev-testing-automation"

documentation:
    required_fields:
        - purpose
        - owner
        - expiration_date
        - permissions_rationale
        - rotation_schedule

Lifecycle Management:

lifecycle_stages:
    creation:
        - justify_business_need
        - approve_permissions
        - document_purpose
        - set_expiration_date

    active:
        - monitor_usage
        - review_permissions
        - track_expiration
        - audit_activity

    retirement:
        - notify_stakeholders
        - update_documentation
        - revoke_access
        - archive_audit_logs

Troubleshooting

Common Issues

Authentication Failures:

# Test API key validity
9n9s-cli auth test-key key_abc123

# Check key permissions
9n9s-cli auth describe-key key_abc123

# Verify IP allowlist
curl -H "Authorization: Bearer $API_KEY" \
  https://api.9n9s.com/v1/auth/verify

Permission Errors:

# Check required permissions for operation
9n9s-cli auth required-permissions \
  --operation "create_monitor"

# Audit current key permissions
9n9s-cli auth audit-permissions key_abc123

# Compare permissions between keys
9n9s-cli auth compare-keys key_abc123 key_def456

Rate Limiting:

# Check current rate limit status
9n9s-cli auth rate-limit-status key_abc123

# Optimize API usage patterns
9n9s-cli auth usage-analysis \
  --recommendations \
  --key key_abc123

Emergency Procedures

Compromised Key Response:

# Immediate key revocation
9n9s-cli auth emergency-revoke key_abc123 \
  --reason "Security incident #INC-2024-001"

# Generate incident report
9n9s-cli auth incident-report \
  --key key_abc123 \
  --include-usage-history

# Notify security team
9n9s-cli auth notify-security \
  --incident "compromised_key" \
  --key key_abc123

Mass Key Rotation:

# Rotate all keys for user
9n9s-cli auth bulk-rotate \
  --user [email protected] \
  --notify-channels "slack-security"

# Rotate all expiring keys
9n9s-cli auth bulk-rotate \
  --expiring-within "7 days" \
  --dry-run  # Test first

API Keys

API Key Types

Personal Access Tokens

Service Account Keys

Integration Keys

Creating API Keys

Web Interface

CLI Interface

API Creation

Permissions and Scopes

Permission Types

Scope Patterns

Security Features

Expiration Management

IP Allowlisting

Rate Limiting

Key Management

Key Rotation

Key Deactivation

Monitoring and Auditing

Usage Monitoring

Audit Logging

Integration Examples

CI/CD Integration

Infrastructure as Code

Best Practices

Security Best Practices

Operational Best Practices

Troubleshooting

Common Issues

Emergency Procedures

Next Steps