Global Configurator -- Connections API

Connections store the credentials and configuration needed to communicate with external systems. Each connection has a type (e.g., email-smtp, database-mysql, ssh) that determines which fields are required.

Base URL: http://localhost:8081

Prefix: /connection

Endpoints

Method	Path	Description	Authority
POST	/connection/upsert	Create or update a connection	GlobalConfigurator:Connection:upsert
GET	/connection/\{id\}	Get connection by ID	--
GET	/connection/name/\{connectionName\}	Get connection by name	--
DELETE	/connection/delete/\{id\}	Delete connection by ID	GlobalConfigurator:Connection:delete
POST	/connection/checkUniqueIdentifiers	Check for duplicate connections	--
POST	/connection/search	Search connections with filters	GlobalConfigurator:Connection:read
GET	/connection/\{name\}/exists	Check if connection name exists	GlobalConfigurator:Connection:read
GET	/connection/type/\{connectionType\}	Get connections by type	GlobalConfigurator:Connection:read
GET	/connection/category/\{category\}	Get connections by category	GlobalConfigurator:Connection:read
POST	/connection/bulk-delete	Delete multiple connections	GlobalConfigurator:Connection:delete
POST	/connection/decrypt	Decrypt encrypted values	--
GET	/connection/options	Get connection options for dropdowns	GlobalConfigurator:Connection:read

---

POST /connection/upsert

Create a new connection or update an existing one. Sensitive fields (passwords, tokens, keys) are automatically encrypted before storage.

Email SMTP Connection

{
  "name": "Production Email Server",
  "connectionType": "email-smtp",
  "category": "communication",
  "description": "SMTP server for sending automated emails.",
  "variables": {
    "host": "smtp.example.com",
    "port": "587",
    "username": "automations@example.com",
    "password": "s3cur3-p@ssw0rd",
    "encryption": "STARTTLS",
    "fromAddress": "automations@example.com",
    "fromName": "Automation Hub"
  }
}

MySQL Database Connection

{
  "name": "Data Warehouse",
  "connectionType": "database-mysql",
  "category": "database",
  "description": "Production data warehouse for reporting queries.",
  "variables": {
    "host": "db.example.com",
    "port": "3306",
    "database": "data_warehouse",
    "username": "reporting_user",
    "password": "db-p@ssw0rd",
    "useSSL": "true"
  }
}

SSH Connection

{
  "name": "Production App Server",
  "connectionType": "ssh",
  "category": "protocol",
  "description": "SSH access to production application server.",
  "variables": {
    "host": "app-server.example.com",
    "port": "22",
    "username": "deploy",
    "authMethod": "privateKey",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
    "passphrase": ""
  }
}

AWS S3 Connection

{
  "name": "Report Storage Bucket",
  "connectionType": "aws-s3",
  "category": "cloud",
  "description": "S3 bucket for storing generated reports.",
  "variables": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "bucket": "automation-reports"
  }
}

Slack Connection

{
  "name": "Engineering Slack",
  "connectionType": "slack",
  "category": "communication",
  "description": "Slack workspace for engineering team notifications.",
  "variables": {
    "botToken": "xoxb-1234567890-abcdefghijklmnop",
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "defaultChannel": "#automation-alerts"
  }
}

REST API Connection

{
  "name": "CRM API",
  "connectionType": "rest-api",
  "category": "api",
  "description": "REST API for the internal CRM system.",
  "variables": {
    "baseUrl": "https://crm.example.com/api/v2",
    "authType": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "headers": "{\"X-Custom-Header\": \"automation-hub\"}"
  }
}

Response (all types):

{
  "status": "success",
  "message": "Connection saved successfully",
  "data": {
    "id": "conn-abc-123",
    "name": "Production Email Server",
    "connectionType": "email-smtp",
    "category": "communication",
    "description": "SMTP server for sending automated emails.",
    "variables": {
      "host": "smtp.example.com",
      "port": "587",
      "username": "automations@example.com",
      "password": "ENC(aBcDeFgHiJkLmNoPqRsTuVwXyZ==)",
      "encryption": "STARTTLS",
      "fromAddress": "automations@example.com",
      "fromName": "Automation Hub"
    },
    "createdAt": "2026-04-02T09:00:00Z",
    "updatedAt": "2026-04-02T09:00:00Z"
  }
}

Note that sensitive fields (like password) are returned in encrypted form.

---

GET /connection/{id}

Get a connection by its unique ID. Sensitive fields are returned encrypted.

Example:

curl http://localhost:8081/connection/conn-abc-123

Response:

{
  "status": "success",
  "message": "Connection fetched successfully",
  "data": {
    "id": "conn-abc-123",
    "name": "Production Email Server",
    "connectionType": "email-smtp",
    "category": "communication",
    "variables": {
      "host": "smtp.example.com",
      "port": "587",
      "username": "automations@example.com",
      "password": "ENC(aBcDeFgHiJkLmNoPqRsTuVwXyZ==)"
    }
  }
}

---

GET /connection/name/{connectionName}

Get a connection by its name.

Example:

curl http://localhost:8081/connection/name/Production%20Email%20Server

Returns the same structure as GET /connection/\{id\}.

---

DELETE /connection/delete/{id}

Delete a connection by its ID.

Example:

curl -X DELETE http://localhost:8081/connection/delete/conn-abc-123

Response:

{
  "status": "success",
  "message": "Connection deleted successfully",
  "data": null
}

---

POST /connection/checkUniqueIdentifiers

Check whether a connection with the same unique fields (name and type) already exists. Useful before creating a connection to avoid duplicates.

Request body:

{
  "name": "Production Email Server",
  "connectionType": "email-smtp"
}

Response:

{
  "status": "success",
  "message": "Connection with the same unique fields exists",
  "data": {
    "isPresent": true,
    "existingConnectionId": "conn-abc-123"
  }
}

---

POST /connection/search

Search connections with pagination and column-level filters.

Request body:

{
  "page": 0,
  "size": 10,
  "sortBy": "name",
  "sortOrder": "asc",
  "searchText": "email",
  "filters": {
    "connectionType": {
      "operator": "or",
      "constraints": [
        { "value": "email-smtp", "matchMode": "equals" },
        { "value": "slack", "matchMode": "equals" }
      ]
    }
  }
}

Response:

{
  "status": "Success",
  "message": "Connection fetched successfully",
  "data": [
    {
      "id": "conn-abc-123",
      "name": "Production Email Server",
      "connectionType": "email-smtp",
      "category": "communication"
    }
  ],
  "meta": {
    "totalElements": 1,
    "page": 0,
    "size": 10
  }
}

---

GET /connection/{name}/exists

Check whether a connection with the given name exists. Optionally pass an id query parameter to exclude a specific connection from the check.

Example:

curl "http://localhost:8081/connection/Production%20Email%20Server/exists?id=conn-abc-123"

Response:

{
  "status": "Success",
  "message": "Connection presence check completed",
  "data": false
}

---

GET /connection/type/{connectionType}

List all connections of a specific type.

Example:

curl http://localhost:8081/connection/type/database-mysql

Response:

{
  "status": "success",
  "message": "Connections fetched successfully",
  "data": [
    {
      "id": "conn-dw-001",
      "name": "Data Warehouse",
      "connectionType": "database-mysql",
      "category": "database"
    },
    {
      "id": "conn-app-db",
      "name": "Application Database",
      "connectionType": "database-mysql",
      "category": "database"
    }
  ]
}

---

GET /connection/options

Get connection options formatted for dropdown menus. Optionally filter by connection type(s).

Example:

curl "http://localhost:8081/connection/options?type=email-smtp&type=slack"

Response:

[
  { "label": "Production Email Server", "value": "conn-abc-123" },
  { "label": "Engineering Slack", "value": "conn-slack-001" }
]

---

POST /connection/decrypt

Decrypt an encrypted value. Used by the UI to reveal passwords and sensitive fields.

Request body:

{
  "encryptedValue": "ENC(aBcDeFgHiJkLmNoPqRsTuVwXyZ==)"
}

Response:

{
  "status": "success",
  "message": "Value Decrypted successfully",
  "data": {
    "decryptedValue": "s3cur3-p@ssw0rd"
  }
}