Create Private Location

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

Basic Settings

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.)

Naming Guidelines

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"
}

Supported Icons

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

Regional Reference

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

Automatic API Key Creation

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.

Key Security

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

Multiple Keys

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

1. Save the API Key

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"

2. Install the Checkly Agent

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"

3. Verify Connection

Check that the agent connects successfully:

Wait a few minutes for the agent to start
Check the private location status via API
Look for status: "ACTIVE" and recent lastHeartbeat
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"

4. Assign Checks

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

Naming Strategy

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”

Security Considerations

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

Infrastructure Planning

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

Organization

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.

Authorizations

Authorization

string

header

required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here.

Your API key is like a password: keep it secure!

Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID.

For example, set Authorization header while using cURL:

curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

x-checkly-account

string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Body

application/json

name

string

required

The name assigned to the private location.

Example:

"New Private Location"

slugName

string

required

Valid slug name.

Example:

"new-private-location"

icon

string

default:location

Example:

"location"

proxyUrl

string

A proxy for outgoing API check HTTP calls from your private location.

Example:

"https://user:password@164.92.149.127:3128"

Response

Created

string

required

Example:

"0baf2a80-7266-44af-b56c-2af7086782ee"

name

string

required

The name assigned to the private location.

Example:

"New Private Location"

slugName

string

required

Valid slug name.

Example:

"new-private-location"

created_at

string<date>

required

icon

string

The private location icon.

Example:

"location"

updated_at

string<date>

checkAssignments

object[]

The check this private location has assigned.

Show child attributes

groupAssignments

object[]

The group this private location has assigned.

Show child attributes

keys

object[]

Show child attributes

proxyUrl

string

A proxy for outgoing API check HTTP calls from your private location.

Example:

"https://user:password@164.92.149.127:3128"

Platform

Detect

Communicate

Resolve

Create Private Location

Overview

Request Example

Response Example

Configuration Options

API Key Management

Code Examples

Next Steps After Creation

Best Practices

Authorizations

Headers

Body

Response

Platform

Detect

Communicate

Resolve

​Overview

​Request Example

​Response Example

​Configuration Options

​API Key Management

​Code Examples

​Next Steps After Creation

​Best Practices

Authorizations

Headers

Body

Response

Overview

Request Example

Response Example

Configuration Options

API Key Management

Code Examples

Next Steps After Creation

Best Practices