Miot Connections

ModularIoT Connections Skill

Prerequisites

The miot CLI must be available. Run commands via:

• npx @microboxlabs/miot-cli <command> (no install needed), or
• miot <command> (if globally installed)

Configuration requires one of:

1. --base-url, --token, and --organization flags on every call
2. MIOT_BASE_URL, MIOT_TOKEN, and MIOT_ORGANIZATION_ID environment variables
3. A ~/.miotrc.json profile selected with --profile <name>

Always add --output json to CLI calls and parse the JSON result.

Domain Model

Organization
 └── Integration Connections
      ├── Credential Profiles  ← auth material and public auth config
      ├── Connections           ← provider base URL, provider type, status, metadata
      ├── Operations            ← method/path contracts for provider endpoints
      └── Connection Tests      ← marks a connection ACTIVE when the contract validates

Key relationships:

• A credential profile stores auth config separately from a connection.
• A connection references exactly one credential profile.
• Operations belong to a connection and describe provider endpoint contracts.
• Connection tests currently validate the connection contract and update the connection status.

Common Workflows

"List the integration connections"

miot connections list --output json

Summarize by name, provider type, status, base URL, and last test result.

"Create a credential profile"

1. Choose an authType: NONE, BEARER_TOKEN, API_KEY_HEADER, API_KEY_QUERY, BASIC, OAUTH2_CLIENT_CREDENTIALS, or CUSTOM_HEADERS.
2. Put non-secret settings in --public-config-json.
3. Put secret material in --secret-config-json.
4. Run:

   miot connections profiles create \
     --display-name "<name>" \
     --auth-type <authType> \
     --public-config-json '<json-object>' \
     --secret-config-json '<json-object>' \
     --output json
   

Never print secret values back to the user. The API returns only secretPreview.

"Create a connection"

1. Create or identify the credential profile:

   miot connections profiles list --output json
   

2. Choose a provider type: POSTGREST, ALERCE_TMS, N8N, AUTH0, ECM, or CUSTOM_HTTP.
3. Create the connection:

   miot connections create \
     --name "<name>" \
     --provider <providerType> \
     --provider-base-url "<url>" \
     --credential-profile <profileId> \
     --metadata-json '<json-object>' \
     --output json
   

"Add an operation to a connection"

miot connections operations create <connectionId> \
  --name "<operation name>" \
  --method GET \
  --path "/health" \
  --request-schema-json '{}' \
  --response-schema-json '{}' \
  --test-operation \
  --output json

Use --test-operation for the operation intended to represent a health check or probe.

"Test a connection"

miot connections test <connectionId> --method GET --path "/health" --output json

If successful, the connection status becomes ACTIVE and lastTestResult becomes true.

"Show the complete setup for a connection"

1. Get the connection:

   miot connections get <connectionId> --output json
   

2. List its operations:

   miot connections operations list <connectionId> --output json
   

3. If credential profile details are needed, list profiles and match by credentialProfileId.

Error Handling

CLI errors return { "error": { "status": N, "message": "..." } } or { "error": { "message": "..." } }.

Common cases:

Explain the error in plain language and suggest the next command to inspect state.

Business Rules

• Organization is required for all connections commands. Use --organization, MIOT_ORGANIZATION_ID, or a profile with organizationId.
• Supported provider types: POSTGREST, ALERCE_TMS, N8N, AUTH0, ECM, CUSTOM_HTTP.
• Supported auth types: NONE, BEARER_TOKEN, API_KEY_HEADER, API_KEY_QUERY, BASIC, OAUTH2_CLIENT_CREDENTIALS, CUSTOM_HEADERS.
• JSON flags must be JSON objects, not arrays or scalar values.
• Treat secretConfig values as sensitive. Do not echo, log, or summarize raw secrets.
• Use --provider-base-url for the external provider URL. --base-url is the ModularIoT API base URL.
• A new connection starts as DRAFT; successful test changes it to ACTIVE.

Full CLI Reference

For the complete list of commands, flags, and JSON output shapes, read references/reference.md.