Authentication

Statly's MCP server supports multiple authentication methods to connect AI agents to your organization's data.

Authentication Methods

API Key Authentication

The most common method. Create an API key in your dashboard and pass it as a header.

Create an API Key

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Use in MCP Client

Add the Authorization header to your configuration:

{
  "mcpServers": {
    "statly": {
      "url": "https://mcp.statly.live/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}

Permission Scopes

API keys can have granular permissions for each resource type:

{
  "monitors": "read" | "write" | "none",
  "incidents": "read" | "write" | "none",
  "maintenance": "read" | "write" | "none",
  "subscribers": "read" | "write" | "none",
  "integrations": "read" | "write" | "none",
  "status": "read" | "none"
}

Permission Levels

Example Scopes

Read-Only Key (for dashboards, monitoring):

{
  "monitors": "read",
  "incidents": "read",
  "maintenance": "read",
  "subscribers": "read",
  "integrations": "read",
  "status": "read"
}

Incident Management Key (for on-call tools):

{
  "monitors": "read",
  "incidents": "write",
  "maintenance": "read",
  "subscribers": "none",
  "integrations": "none",
  "status": "read"
}

Full Access (legacy, use *):

"*"

Device Authorization Flow

For AI clients that support OAuth device flow (RFC 8628), users can authorize interactively without copying API keys.

How It Works

{
  "device_code": "abc123...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://statly.live/mcp/authorize",
  "expires_in": 900,
  "interval": 5
}

Client Implementation

If you're building an MCP client with device flow support:

// 1. Start device flow
const response = await fetch('https://mcp.statly.live/auth/device', {
  method: 'POST'
});
const { device_code, user_code, verification_uri } = await response.json();
 
// 2. Display to user
console.log(`Visit ${verification_uri} and enter: ${user_code}`);
 
// 3. Poll for authorization
while (true) {
  await new Promise(r => setTimeout(r, 5000)); // Poll interval
 
  const pollResponse = await fetch('https://mcp.statly.live/auth/device/poll', {
    method: 'POST',
    body: JSON.stringify({ device_code })
  });
 
  const result = await pollResponse.json();
 
  if (result.status === 'authorized') {
    // Store organization_id and use it for subsequent requests
    break;
  }
  if (result.status === 'expired') {
    // Start over
    break;
  }
  // status === 'pending' - keep polling
}

Rate Limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1703001234

When rate limited, you'll receive a 429 response with Retry-After header.

Security Best Practices

Protect Your API Keys

• Never commit API keys to version control
• Use environment variables or secure secret managers
• Rotate keys periodically
• Use minimum required permissions

Audit Key Usage

View API key activity in Dashboard → Settings → API Keys → Usage.

Revoke Compromised Keys

If a key is exposed, immediately delete it from the dashboard. All requests using that key will fail.

Troubleshooting

"Invalid API key"

• Key may have been deleted or rotated
• Check for typos or extra whitespace
• Ensure you're using the full key including sk_live_ prefix

"Permission denied"

• Key doesn't have required scope for the operation
• Check key permissions in dashboard

"Organization not found"

• Key is valid but organization was deleted
• Generate a new key from the correct organization