Skip to main content

​
Overview

Create a new private location to run checks from your own infrastructure. Private locations allow you to monitor internal services, comply with regulatory requirements, or test from specific geographic locations.
After creating a private location, you’ll need to install and configure the Checkly Agent in your infrastructure for it to become active.

​
Request Example

{
  "name": "AWS Production Data Center",
  "slugName": "aws-prod-dc",
  "region": "us-east-1",
  "tags": ["aws", "production", "primary"],
  "icon": "aws"
}

​
Response Example

{
  "id": "pl_789123456",
  "name": "AWS Production Data Center",
  "slugName": "aws-prod-dc",
  "status": "INACTIVE",
  "region": "us-east-1",
  "tags": ["aws", "production", "primary"],
  "icon": "aws",
  "agentVersion": null,
  "lastHeartbeat": null,
  "checksCount": 0,
  "apiKeys": [
    {
      "id": "key_123456",
      "name": "Default API Key",
      "keyHash": "ck_live_***masked***",
      "createdAt": "2024-01-25T10:30:00.000Z"
    }
  ],
  "createdAt": "2024-01-25T10:30:00.000Z",
  "updatedAt": "2024-01-25T10:30:00.000Z"
}

​
Configuration Options

Required Fields:
  • name (string): Human-readable name for the private location
  • slugName (string): URL-safe identifier (lowercase, hyphens allowed)
Optional Fields:
  • region (string): AWS region identifier for geographic reference
  • tags (array): Tags for organization and filtering
  • icon (string): Icon identifier for the UI (aws, gcp, azure, docker, kubernetes, etc.)
Name Requirements:
  • Must be unique within your account
  • Can contain letters, numbers, spaces, and common punctuation
  • Maximum 255 characters
  • Should be descriptive and meaningful
Slug Name Requirements:
  • Must be unique within your account
  • Lowercase letters, numbers, and hyphens only
  • Cannot start or end with a hyphen
  • Maximum 63 characters
  • Used in API calls and URLs
Examples:
{
  "name": "Production Data Center US-East",
  "slugName": "prod-dc-us-east"
}
Choose an icon that represents your infrastructure:
  • aws - Amazon Web Services
  • gcp - Google Cloud Platform
  • azure - Microsoft Azure
  • docker - Docker containers
  • kubernetes - Kubernetes clusters
  • server - Generic server
  • cloud - Generic cloud
  • datacenter - Data center
  • office - Office location
Use standard AWS region identifiers for consistency:
  • us-east-1 - US East (N. Virginia)
  • us-west-2 - US West (Oregon)
  • eu-west-1 - Europe (Ireland)
  • ap-southeast-1 - Asia Pacific (Singapore)
  • Or use custom identifiers for your locations

​
API Key Management

When you create a private location, Checkly automatically generates:
  • A default API key for agent authentication
  • Secure key with appropriate permissions
  • Initial key named “Default API Key”
The API key is used by the Checkly Agent to authenticate with Checkly services.
  • API keys are shown only once during creation
  • Keys are hashed and masked in subsequent API responses
  • Store keys securely in your infrastructure
  • Rotate keys regularly for security
You can create multiple API keys for:
  • Different environments (staging, production)
  • Key rotation without downtime
  • Team or service separation
  • Backup authentication methods

​
Code Examples

curl -X POST "https://api.checklyhq.com/v1/private-locations" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-Premise European Office",
    "slugName": "onprem-eu-office",
    "region": "eu-west-1",
    "tags": ["on-premise", "europe", "office"],
    "icon": "office"
  }'

​
Next Steps After Creation

Critical: Save the API key immediately after creation:
  • The key is only shown once in the creation response
  • Store it securely in your secrets management system
  • You’ll need it to configure the Checkly Agent
# Example: Save to environment variable
export CHECKLY_API_KEY="ck_live_your_actual_key_here"
Download and install the agent in your infrastructure:
# Example Docker installation
docker run -d \
  --name checkly-agent \
  --restart unless-stopped \
  -e CHECKLY_API_KEY="ck_live_your_actual_key_here" \
  -e CHECKLY_PRIVATE_LOCATION_SLUG="your-location-slug" \
  checkly/agent:latest
Or using Kubernetes:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkly-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: checkly-agent
  template:
    metadata:
      labels:
        app: checkly-agent
    spec:
      containers:
      - name: agent
        image: checkly/agent:latest
        env:
        - name: CHECKLY_API_KEY
          valueFrom:
            secretKeyRef:
              name: checkly-secret
              key: api-key
        - name: CHECKLY_PRIVATE_LOCATION_SLUG
          value: "your-location-slug"
Check that the agent connects successfully:
  1. Wait a few minutes for the agent to start
  2. Check the private location status via API
  3. Look for status: "ACTIVE" and recent lastHeartbeat
  4. Monitor agent logs for any connection issues
# Check status
curl -X GET "https://api.checklyhq.com/v1/private-locations/pl_your_id" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"
Configure checks to use your private location:
  • Update existing checks to include your private location
  • Create new checks that target your private location
  • Use check groups to apply the location to multiple checks
{
  "privateLocations": ["your-location-slug"]
}

​
Best Practices

Use consistent naming conventions:
  • Environment: Include environment (prod, staging, dev)
  • Technology: Specify platform (aws, k8s, docker)
  • Location: Include geographic or logical location
  • Purpose: Indicate the purpose or team
Examples:
  • “Production AWS US-East”
  • “Staging Kubernetes EU”
  • “Dev Docker Local”
  • API Key Storage: Use secure secrets management
  • Network Access: Restrict outbound access to required endpoints
  • Agent Updates: Keep agent versions current
  • Monitoring: Monitor agent health and connectivity
  • Resource Requirements: Ensure adequate CPU and memory
  • Network Connectivity: Plan for outbound HTTPS access
  • High Availability: Consider running multiple agents
  • Scaling: Plan for check volume and concurrent execution
  • Tagging: Use consistent tags for filtering and organization
  • Documentation: Document the purpose and configuration
  • Access Control: Limit who can create and manage private locations
  • Monitoring: Set up alerts for private location health
Remember to save the API key immediately after creation - it’s only shown once! You’ll need this key to configure the Checkly Agent in your infrastructure.