API Keys

The API Keys endpoint allows you to programmatically create and manage API keys with specific permission scopes. This enables fine-grained access control for different integrations, services, and team members.

Authentication

Managing API keys requires authentication with an existing API key that has appropriate permissions. Note that you cannot create keys with more permissions than your current key has.

Quick Start

Create an API Key

curl --user EXISTING_API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "CI/CD Pipeline",
        "kind": "custom",
        "scopes": ["monitor:read", "monitor:write", "telemetry:write"]
    }' \
    https://cronitor.io/api/keys

List All API Keys

curl https://cronitor.io/api/keys -u API_KEY:

API Keys

List API Keys

Retrieve all API keys for your organization.

Endpoint

GET https://cronitor.io/api/keys

Example

curl https://cronitor.io/api/keys -u API_KEY:

Response

{
  "page": 1,
  "page_size": 50,
  "total_count": 3,
  "data": [
    {
      "key": "abc123def456...",
      "name": "Main API Key",
      "kind": "custom",
      "scopes": ["monitor:read", "monitor:write", "telemetry:write", "issue:read", "issue:write"],
      "immutable": false,
      "last_used": "2023-12-01T14:30:00Z",
      "created": "2023-01-15T10:00:00Z",
      "updated": "2023-06-20T08:00:00Z"
    },
    {
      "key": "xyz789...",
      "name": "Telemetry Only",
      "kind": "telemetry",
      "scopes": ["telemetry:write"],
      "immutable": true,
      "last_used": "2023-12-01T15:45:00Z",
      "created": "2023-03-10T12:00:00Z",
      "updated": "2023-03-10T12:00:00Z"
    }
  ]
}

Create an API Key

Create a new API key with specific permissions.

Endpoint

POST https://cronitor.io/api/keys

Request Body

{
  "name": "Deployment Script",
  "kind": "custom",
  "scopes": ["monitor:read", "monitor:write"]
}

Parameters

• name (string, required) - Display name for the API key
• kind (string, required) - Type of API key: telemetry, sdk_integration, or custom
• scopes (array of strings, required for custom kind) - Permission scopes for the key

Key Kinds

Available Scopes

Example: Telemetry-Only Key

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Production Telemetry",
        "kind": "telemetry"
    }' \
    https://cronitor.io/api/keys

Example: Custom Key with Specific Scopes

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Read-Only Dashboard",
        "kind": "custom",
        "scopes": ["monitor:read", "issue:read"]
    }' \
    https://cronitor.io/api/keys

Response

{
  "key": "new_key_abc123...",
  "name": "Deployment Script",
  "kind": "custom",
  "scopes": ["monitor:read", "monitor:write"],
  "immutable": false,
  "last_used": null,
  "created": "2023-12-01T10:00:00Z",
  "updated": "2023-12-01T10:00:00Z"
}

Important: The full API key is only returned once when created. Store it securely.

Get an API Key

Retrieve details for a specific API key.

Endpoint

GET https://cronitor.io/api/keys/:key

Example

curl https://cronitor.io/api/keys/abc123def456 -u API_KEY:

Response

{
  "key": "abc123def456...",
  "name": "CI/CD Pipeline",
  "kind": "custom",
  "scopes": ["monitor:read", "monitor:write", "telemetry:write"],
  "immutable": false,
  "last_used": "2023-12-01T14:30:00Z",
  "created": "2023-06-15T10:00:00Z",
  "updated": "2023-06-15T10:00:00Z"
}

Update an API Key

Update an API key's name or scopes. Immutable keys (telemetry and SDK keys) cannot have their scopes changed.

Endpoint

PUT https://cronitor.io/api/keys/:key

Request Body

{
  "name": "CI/CD Pipeline (Production)",
  "scopes": ["monitor:read", "monitor:write", "telemetry:write", "issue:read"]
}

Example

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Updated Key Name",
        "scopes": ["monitor:read", "telemetry:write"]
    }' \
    https://cronitor.io/api/keys/abc123def456

Response

Returns the updated API key object.

Note: You cannot add scopes that exceed your current key's permissions.

Delete an API Key

Delete an API key. This action is irreversible.

Endpoint

DELETE https://cronitor.io/api/keys/:key

Example

curl --request DELETE https://cronitor.io/api/keys/old_key_123 -u API_KEY:

Response

Returns HTTP 204 No Content on success.

API Key Attributes

key[string] read-only

The API key value. Only shown in full when the key is first created.

name[string] **required**

Display name for the API key. Use descriptive names to identify the key's purpose.

kind[string] **required**

Type of API key: telemetry, sdk_integration, or custom.

scopes[array of strings]

Permission scopes granted to this key. For telemetry and sdk_integration keys, scopes are fixed.

immutable[boolean] read-only

Whether the key's scopes can be modified. Telemetry and SDK keys are immutable.

last_used[timestamp] read-only

ISO 8601 timestamp of when the key was last used to make an API request.

created[timestamp] read-only

ISO 8601 timestamp of when the key was created.

updated[timestamp] read-only

ISO 8601 timestamp of when the key was last updated.

Best Practices

• Use least-privilege: Create keys with only the scopes needed for their specific purpose
• Separate by environment: Use different keys for production, staging, and development
• Use telemetry keys for agents: When only sending pings, use telemetry-only keys
• Rotate keys regularly: Periodically create new keys and retire old ones
• Monitor key usage: Check last_used to identify unused keys for cleanup
• Name keys descriptively: Include the purpose and environment (e.g., "CI/CD Production", "Staging Dashboard")
• Never commit keys to code: Use environment variables or secret management tools

Security Considerations

• API keys provide full access according to their scopes—treat them like passwords
• The full key value is only shown once at creation time
• Keys cannot be recovered if lost; create a new key instead
• Deleting a key immediately revokes all access for that key
• Consider using telemetry-only keys for client-side or less trusted environments