Maintainx Install AuthCAUTION

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: maintainx-install-auth
description: 'Install and configure MaintainX REST API authentication.

  Use when setting up a new MaintainX integration, configuring API keys,

  or initializing MaintainX API access in your project.

  Trigger with phrases like "install maintainx", "setup maintainx",

  "maintainx auth", "configure maintainx API key", "maintainx credentials".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(curl:*), Grep
version: 1.11.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- maintainx
- api
- authentication
compatibility: Designed for Claude Code
---
# MaintainX Install & Auth

## Overview

Set up MaintainX REST API authentication and configure your development environment for CMMS integration.

## Prerequisites

- Node.js 18+ or Python 3.10+
- MaintainX account with API access (Professional or Enterprise plan)
- Admin access to generate API keys

## Instructions

### Step 1: Generate API Key

1. Log into MaintainX at https://app.getmaintainx.com
2. Navigate to **Settings** > **Integrations**
3. Click **New Key** > **Generate Key**
4. Copy and securely store your API key (shown only once)

### Step 2: Configure Environment Variables

```bash
# Set environment variable
export MAINTAINX_API_KEY="your-api-key-here"

# Or create .env file
echo 'MAINTAINX_API_KEY=your-api-key' >> .env

# For multi-organization tokens, also set:
export MAINTAINX_ORG_ID="your-organization-id"
```

### Step 3: Create API Client Wrapper

```typescript
// src/maintainx/client.ts
import axios, { AxiosInstance, AxiosError } from 'axios';

export class MaintainXClient {
  private client: AxiosInstance;
  private baseUrl = 'https://api.getmaintainx.com/v1';

  constructor(apiKey?: string, orgId?: string) {
    const key = apiKey || process.env.MAINTAINX_API_KEY;
    if (!key) {
      throw new Error('MAINTAINX_API_KEY is required');
    }

    this.client = axios.create({
      baseURL: this.baseUrl,
      headers: {
        'Authorization': `Bearer ${key}`,
        'Content-Type': 'application/json',
        ...(orgId && { 'X-Organization-Id': orgId }),
      },
    });

    this.client.interceptors.response.use(
      response => response,
      this.handleError
    );
  }

  private handleError(error: AxiosError) {
    if (error.response) {
      const { status, data } = error.response;
      console.error(`MaintainX API Error [${status}]:`, data);
    }
    throw error;
  }

  // Core API methods
  async getWorkOrders(params?: WorkOrderQueryParams) {
    return this.client.get('/workorders', { params });
  }

  async getWorkOrder(id: string) {
    return this.client.get(`/workorders/${id}`);
  }

  async createWorkOrder(data: CreateWorkOrderInput) {
    return this.client.post('/workorders', data);
  }

  async getAssets(params?: AssetQueryParams) {
    return this.client.get('/assets', { params });
  }

  async getLocations(params?: LocationQueryParams) {
    return this.client.get('/locations', { params });
  }

  async getUsers(params?: UserQueryParams) {
    return this.client.get('/users', { params });
  }
}

// Type definitions
interface WorkOrderQueryParams {
  cursor?: string;
  limit?: number;
  status?: 'OPEN' | 'IN_PROGRESS' | 'ON_HOLD' | 'DONE';
}

interface CreateWorkOrderInput {
  title: string;
  description?: string;
  priority?: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
  assignees?: string[];
  assetId?: string;
  locationId?: string;
  dueDate?: string;
}

interface AssetQueryParams {
  cursor?: string;
  limit?: number;
  locationId?: string;
}

interface LocationQueryParams {
  cursor?: string;
  limit?: number;
}

interface UserQueryParams {
  cursor?: string;
  limit?: number;
}
```

### Step 4: Verify Connection

```typescript
// test-connection.ts
import { MaintainXClient } from './maintainx/client';

async function testConnection() {
  const client = new MaintainXClient();

  try {
    const response = await client.getUsers({ limit: 1 });
    console.log('Connection successful!');
    console.log('Organization has users:', response.data.users.length > 0);
    return true;
  } catch (error) {
    console.error('Connection failed:', error);
    return false;
  }
}

testConnection();
```

```bash
# Run test
npx ts-node test-connection.ts
```

### Python Alternative

```python
# maintainx_client.py
import os
import requests
from typing import Optional, Dict, Any

class MaintainXClient:
    BASE_URL = "https://api.getmaintainx.com/v1"

    def __init__(self, api_key: Optional[str] = None, org_id: Optional[str] = None):
        self.api_key = api_key or os.environ.get("MAINTAINX_API_KEY")
        if not self.api_key:
            raise ValueError("MAINTAINX_API_KEY is required")

        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        if org_id:
            self.headers["X-Organization-Id"] = org_id

    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        url = f"{self.BASE_URL}{endpoint}"
        response = requests.request(method, url, headers=self.headers, **kwargs)
        response.raise_for_status()
        return response.json()

    def get_work_orders(self, **params) -> Dict[str, Any]:
        return self._request("GET", "/workorders", params=params)

    def create_work_order(self, data: Dict[str, Any]) -> Dict[str, Any]:
        return self._request("POST", "/workorders", json=data)

    def get_assets(self, **params) -> Dict[str, Any]:
        return self._request("GET", "/assets", params=params)

    def get_locations(self, **params) -> Dict[str, Any]:
        return self._request("GET", "/locations", params=params)

# Test connection
if __name__ == "__main__":
    client = MaintainXClient()
    users = client._request("GET", "/users", params={"limit": 1})
    print("Connection successful!")
    print(f"Found {len(users.get('users', []))} users")
```

## Output

- Environment variable or `

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

- Admin access to generate API keys

Gates applied: no_behavioural_pass.