--- title: API Keys description: Create and manage API keys with custom scopes to control access to the Cronitor API. --- 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. {% .lead %} ## 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. The [Cronitor MCP server](/docs/mcp-server#use-the-existing-sdk-integration-key) accepts the organization's SDK Integration key as a Bearer token; there is no separate MCP key type. --- ## Quick Start ### Create an API Key ```bash curl --user EXISTING_API_KEY: \ --header "Content-Type: application/json" \ --request POST \ --data '{ "name": "CI/CD Pipeline", "kind": "custom", "scopes": ["monitor:read", "monitor:write", "monitor:telemetry"] }' \ https://cronitor.io/api/keys ``` ### List All API Keys ```bash curl https://cronitor.io/api/keys -u API_KEY: ``` --- ## API Keys ### List API Keys Retrieve all API keys for your organization. #### Endpoint ```bash GET https://cronitor.io/api/keys ``` #### Example ```bash curl https://cronitor.io/api/keys -u API_KEY: ``` #### Response ```json { "page": 1, "page_size": 50, "total_count": 3, "data": [ { "key": "abc123def456...", "name": "Main API Key", "kind": "custom", "scopes": ["monitor:read", "monitor:write", "monitor:telemetry", "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": ["monitor:telemetry"], "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 ```bash POST https://cronitor.io/api/keys ``` #### Request Body ```json { "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 | Kind | Description | Scopes | |------|-------------|--------| | `telemetry` | For sending telemetry events only | `monitor:telemetry` (fixed) | | `sdk_integration` | Full SDK integration | All resource scopes (fixed) | | `custom` | Custom permissions | User-defined | #### Available Scopes | Scope | Description | |-------|-------------| | `monitor:read` | Read monitor configurations and status | | `monitor:write` | Create, update, and delete monitors | | `monitor:telemetry` | Send telemetry events (pings) | | `site:read` | Read RUM site configurations | | `site:write` | Create, update, and delete RUM sites | | `statuspage:read` | Read status page configurations | | `statuspage:write` | Create, update, and delete status pages | | `issue:read` | Read issues and maintenance windows | | `issue:write` | Create, update, and delete issues and maintenance windows | | `integration:read` | List and retrieve notification integrations | | `integration:write` | Create and delete notification integrations | #### Example: Telemetry-Only Key ```bash 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 ```bash 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 ```json { "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 ```bash GET https://cronitor.io/api/keys/:key ``` #### Example ```bash curl https://cronitor.io/api/keys/abc123def456 -u API_KEY: ``` #### Response ```json { "key": "abc123def456...", "name": "CI/CD Pipeline", "kind": "custom", "scopes": ["monitor:read", "monitor:write", "monitor:telemetry"], "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 ```bash PUT https://cronitor.io/api/keys/:key ``` #### Request Body ```json { "name": "CI/CD Pipeline (Production)", "scopes": ["monitor:read", "monitor:write", "monitor:telemetry", "issue:read"] } ``` #### Example ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "name": "Updated Key Name", "scopes": ["monitor:read", "monitor:telemetry"] }' \ 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 ```bash DELETE https://cronitor.io/api/keys/:key ``` #### Example ```bash 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 {% attribute name="key" context="[string] read-only" /%} The API key value. Only shown in full when the key is first created. {% attribute name="name" context="[string] **required**" /%} Display name for the API key. Use descriptive names to identify the key's purpose. {% attribute name="kind" context="[string] **required**" /%} Type of API key: `telemetry`, `sdk_integration`, or `custom`. {% attribute name="scopes" context="[array of strings]" /%} Permission scopes granted to this key. For `telemetry` and `sdk_integration` keys, scopes are fixed. {% attribute name="immutable" context="[boolean] read-only" /%} Whether the key's scopes can be modified. Telemetry and SDK keys are immutable. {% attribute name="last_used" context="[timestamp] read-only" /%} ISO 8601 timestamp of when the key was last used to make an API request. {% attribute name="created" context="[timestamp] read-only" /%} ISO 8601 timestamp of when the key was created. {% attribute name="updated" context="[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