Checkstack Documentation

External Applications (API Keys)

External Applications provide programmatic access to the Checkstack API for non-human clients like CI/CD pipelines, monitoring tools, and custom integrations.

Overview

• Identity Type: Applications are RBAC-controlled identities (like users), not trusted services
• Authentication: Bearer token via the Authorization header
• Access: Enforced by standard RBAC - applications must be assigned roles with appropriate access rules

Creating an Application

1. Navigate to Authentication Settings → Applications tab
2. Click Create Application
3. Enter a name and optional description
4. Copy the secret immediately - it will never be shown again

New applications are automatically assigned the applications role. Assign additional roles via the inline checkboxes in the Applications table.

Token Format

Application secrets follow a structured format:

ck_{applicationId}_{randomSecret}

• ck_: Prefix for easy identification in logs
• applicationId: UUID identifying the application
• randomSecret: Cryptographically random token

Example:

ck_a1b2c3d4-e5f6-7890-abcd-ef1234567890_f8k2mN9xZpW3qR7vL5tY

Authentication

Use the Authorization header with the Bearer scheme:

Authorization: Bearer ck_{applicationId}_{secret}

Calling oRPC Endpoints

All oRPC endpoints are available at /api/{pluginId}/ and accept JSON POST requests.

Basic Example (curl)

curl -X POST https://your-checkstack-instance.com/api/catalog/ \
  -H "Authorization: Bearer ck_YOUR_APP_ID_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"getSystems": {}}'

JavaScript/TypeScript (fetch)

const API_BASE = "https://your-checkstack-instance.com";
const API_KEY = "ck_YOUR_APP_ID_YOUR_SECRET";

// Call a single procedure
async function callRpc<T>(
  pluginId: string,
  procedure: string,
  input?: unknown
): Promise<T> {
  const response = await fetch(`${API_BASE}/api/${pluginId}/`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ [procedure]: input ?? {} }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || `HTTP ${response.status}`);
  }

  const result = await response.json();
  return result[procedure];
}

// Usage examples
const systems = await callRpc("catalog", "getSystems");
const health = await callRpc("healthcheck", "getHealthChecks");

Batching Multiple Calls

oRPC supports batching multiple procedure calls in a single request:

const response = await fetch(`${API_BASE}/api/catalog/`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    getSystems: {},
    getGroups: {},
  }),
});

const { getSystems, getGroups } = await response.json();

Python Example

import requests

API_BASE = "https://your-checkstack-instance.com"
API_KEY = "ck_YOUR_APP_ID_YOUR_SECRET"

def call_rpc(plugin_id: str, procedure: str, input_data=None):
    response = requests.post(
        f"{API_BASE}/api/{plugin_id}/",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={procedure: input_data or {}},
    )
    response.raise_for_status()
    return response.json()[procedure]

# Usage
systems = call_rpc("catalog", "getSystems")

Available Endpoints

Each plugin exposes its procedures at /api/{pluginId}/. Common endpoints include:

Plugin	Endpoint	Example Procedures
catalog	/api/catalog/	getSystems, getGroups
healthcheck	/api/healthcheck/	getHealthChecks, getHistory
maintenance	/api/maintenance/	getWindows, scheduleWindow
incident	/api/incident/	getIncidents, createIncident

Note: Available procedures depend on your application’s assigned access. Check each plugin’s contract definition for the full procedure list and required accesss.

Error Handling

oRPC returns structured error responses:

{
  "code": "FORBIDDEN",
  "message": "Missing access: catalog.catalog.read"
}

Common error codes:

• UNAUTHORIZED: Missing or invalid API key
• FORBIDDEN: Valid key but missing required access
• NOT_FOUND: Procedure or resource not found
• BAD_REQUEST: Invalid input parameters

Security Best Practices

1. Store secrets securely - Use environment variables or secret managers
2. Rotate secrets periodically - Use the “Regenerate Secret” button in the UI
3. Apply least privilege - Assign only the roles/access rules needed
4. Monitor usage - Check the “Last Used” column for inactive applications
5. Delete unused applications - Expired keys stop working immediately

Access Reference

Applications use the same RBAC system as users. To call an endpoint, the application must have a role with the required access rule. Access rule format:

{pluginId}.{accessRuleId}

Example: To call catalog.getSystems, the application needs a role with catalog.catalog.read access rule.

Team Assignments

Applications can be assigned to teams for resource-level access control. When an application is a member of a team, it can access resources that team has been granted access to.

See Teams and Resource-Level Access Control for details on managing team access to resources.

This site is open source. Improve this page.