> For the complete documentation index, see [llms.txt](https://docs.onomondo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onomondo.com/readme/connectors.md).
# Connectors
## Retrieve information for all Connectors
> Returns detailed information for all registered Connectors.\
> Note that sensitive data will not be returned but information around\
> when it was updated and if its set can be found in the \`meta\` object.\
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors":{"get":{"summary":"Retrieve information for all Connectors","description":"Returns detailed information for all registered Connectors.\nNote that sensitive data will not be returned but information around\nwhen it was updated and if its set can be found in the `meta` object.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Add Connector
> Creates a Connector. The \`object\` various depending on the \`type\`.\
> \`passthrough\` and \`tags\` are shared amongst all types though and\
> are the mechanisms to route parts of the traffic around the Connector\
> as well as grouping and access control.\
> \
> \[Read more about Connectors here]\(
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> \
> Note: Some Connectors are not included in the documentation here as they are currently in a beta state.\
> Moreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors":{"post":{"summary":"Add Connector","description":"Creates a Connector. The `object` various depending on the `type`.\n`passthrough` and `tags` are shared amongst all types though and\nare the mechanisms to route parts of the traffic around the Connector\nas well as grouping and access control.\n\n[Read more about Connectors here](https://help.onomondo.com/en/articles/213872-what-are-onomondo-connectors).\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n\nNote: Some Connectors are not included in the documentation here as they are currently in a beta state.\nMoreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\n{% endhint %}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"name":{"type":"string","pattern":"^[-_a-zA-Z0-9]{3,255}$","description":"A descriptive name for the connector (3-255 characters, alphanumeric, hyphens, and underscores only)"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector to create"},"tags":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control (UUIDs)","nullable":true},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}},"required":["host","port","server_name","key","ca","cert"]},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body","default":false}},"required":["host"]},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}},"required":["region","role","publishTopic","subscribeTopic","defaultProtocol","defaultPort"]},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}},"required":["connectionString"]}]}}}}}},"responses":{"200":{"description":"Connector successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["tls","https","aws_iot_core","microsoft_azure_iot"],"description":"The Connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}}
```
## Update Connector
> Use a PATCH request to update an Onomondo Connector in your account.\
> \
> \
> Update one of the settings of your Connector:\
> \- \`name\`: Change the name\
> \- \`type\`: Change the type of the Connector. For this to be successful, you will need to also update the \`options\` field with the new Connector type details.\
> \- \`passthrough\`: An array of objects to exclude being processed up by the connector. Each object requires at least a "protocol" (of either \`udp\`,\`tcp\`, or \`icmp\`).\
> \- \`tags\`: An array of Tag IDs to be associated with a Connector.\
> \- \`options\`: See the \`POST\` requests for each of the Connectors for fields required in the options field.\
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors/{connector_name}":{"patch":{"summary":"Update Connector","description":"Use a PATCH request to update an Onomondo Connector in your account.\n\n\nUpdate one of the settings of your Connector:\n- `name`: Change the name\n- `type`: Change the type of the Connector. For this to be successful, you will need to also update the `options` field with the new Connector type details.\n- `passthrough`: An array of objects to exclude being processed up by the connector. Each object requires at least a \"protocol\" (of either `udp`,`tcp`, or `icmp`).\n- `tags`: An array of Tag IDs to be associated with a Connector.\n- `options`: See the `POST` requests for each of the Connectors for fields required in the options field.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","operationId":"updateConnector","tags":["Connectors"],"parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector (must update options field when changing type)"},"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with a SIM. Tag IDs require string format and can be obtained using GET /tags endpoint. **Caution**: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags."},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options (see POST examples for each connector type)","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}}},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body"}}},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}}},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}}}]}}}}}},"responses":{"200":{"description":"Connector successfully updated","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}}
```
## Remove Connector
> Removes a specific Connector.\
> \
> \
> Note that all mappings to said Connector will need to be\
> removed prior to the removal of the Connector itself, otherwise\
> a \`403\` status code will be encountered.\
> \
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors/{connector_name}":{"delete":{"summary":"Remove Connector","description":"Removes a specific Connector.\n\n\nNote that all mappings to said Connector will need to be\nremoved prior to the removal of the Connector itself, otherwise\na `403` status code will be encountered.\n\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Connector still mapped to some SIMs","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```