> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.9/api-integrations/connectors-management-apis/configurations.md).
# Configurations
## List configurations
> Returns the configurations available to the caller, optionally filtered by type.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).\
> \
> No pagination is applied. The response is further scoped by the caller's visibility rules inside the configurations context.
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations":{"get":{"description":"Returns the configurations available to the caller, optionally filtered by type.\n\nRequires administrative privileges (**administrator or service account**).\n\nNo pagination is applied. The response is further scoped by the caller's visibility rules inside the configurations context.\n","operationId":"TdCxWeb.ConfigurationController.index","parameters":[{"description":"Filter by configuration type. Restricts the result to configurations of the given type. When omitted, all configurations visible to the caller are returned.","in":"query","name":"type","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationIndexResponse"}}},"description":"Configurations"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List configurations","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationIndexResponse":{"additionalProperties":false,"properties":{"data":{"description":"List of configurations","items":{"$ref":"#/components/schemas/Configuration"},"type":"array"}},"required":["data"],"title":"ConfigurationIndexResponse","type":"object"},"Configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content (key-value pairs)","type":"object"},"dynamic_content":{"additionalProperties":true,"description":"Rich content with origin metadata","nullable":true,"type":"object"},"external_id":{"description":"Configuration external identifier","type":"string"},"id":{"description":"Configuration internal ID","type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"secrets_key":{"description":"Key for secrets (null if no secrets)","nullable":true,"type":"string"},"type":{"description":"Configuration type (template name)","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","external_id","type","content"],"title":"Configuration","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Create a configuration
> Creates a new configuration resource.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).\
> \
> \*\*Request body:\*\*\
> \- \`configuration\` (required) – Object containing:\
> \- \`external\_id\` (required, string) – Unique external identifier.\
> \- \`type\` (required, string) – Configuration type.\
> \- \`content\` (optional, object) – Configuration content. May be omitted at creation.\
> \
> The response includes a \`Location\` header pointing to the created configuration.
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations":{"post":{"description":"Creates a new configuration resource.\n\nRequires administrative privileges (**administrator or service account**).\n\n**Request body:**\n- `configuration` (required) – Object containing:\n - `external_id` (required, string) – Unique external identifier.\n - `type` (required, string) – Configuration type.\n - `content` (optional, object) – Configuration content. May be omitted at creation.\n\nThe response includes a `Location` header pointing to the created configuration.\n","operationId":"TdCxWeb.ConfigurationController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationCreateRequest"}}},"description":"Configuration","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationShowResponse"}}},"description":"Created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create a configuration","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationCreateRequest":{"additionalProperties":false,"properties":{"configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content","type":"object"},"external_id":{"description":"Unique external ID","type":"string"},"type":{"description":"Configuration type (template name)","type":"string"}},"required":["external_id","type"],"type":"object"}},"required":["configuration"],"title":"ConfigurationCreateRequest","type":"object"},"ConfigurationShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Configuration"}},"required":["data"],"title":"ConfigurationShowResponse","type":"object"},"Configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content (key-value pairs)","type":"object"},"dynamic_content":{"additionalProperties":true,"description":"Rich content with origin metadata","nullable":true,"type":"object"},"external_id":{"description":"Configuration external identifier","type":"string"},"id":{"description":"Configuration internal ID","type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"secrets_key":{"description":"Key for secrets (null if no secrets)","nullable":true,"type":"string"},"type":{"description":"Configuration type (template name)","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","external_id","type","content"],"title":"Configuration","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnprocessableEntityResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Sign a payload with a configuration
> Signs a caller-provided payload using the signing key stored in the specified configuration.\
> \
> \*\*Request body:\*\*\
> \- \`payload\` (required, object) – Data to be signed. Returned as a JWT signed with HS256 using the configuration's secret key.\
> \
> On success, the response contains the signed token (\`201 Created\`).
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations/{configuration_external_id}/sign":{"post":{"description":"Signs a caller-provided payload using the signing key stored in the specified configuration.\n\n**Request body:**\n- `payload` (required, object) – Data to be signed. Returned as a JWT signed with HS256 using the configuration's secret key.\n\nOn success, the response contains the signed token (`201 Created`).\n","operationId":"TdCxWeb.ConfigurationSignerController.create","parameters":[{"description":"Configuration external ID","in":"path","name":"configuration_external_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationSignRequest"}}},"description":"Sign payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationSignResponse"}}},"description":"Signed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Sign a payload with a configuration","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationSignRequest":{"additionalProperties":false,"properties":{"payload":{"additionalProperties":true,"description":"Payload to be signed","type":"object"}},"required":["payload"],"title":"ConfigurationSignRequest","type":"object"},"ConfigurationSignResponse":{"additionalProperties":false,"properties":{"token":{"description":"Signed JWT token","type":"string"}},"required":["token"],"title":"ConfigurationSignResponse","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxNotFoundResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxNotFoundResponse","type":"object"},"TdCxUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnprocessableEntityResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Get a configuration by external ID
> Fetches a single configuration using its external ID.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).\
> \
> The result is scoped by the caller's visibility rules.
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations/{external_id}":{"get":{"description":"Fetches a single configuration using its external ID.\n\nRequires administrative privileges (**administrator or service account**).\n\nThe result is scoped by the caller's visibility rules.\n","operationId":"TdCxWeb.ConfigurationController.show","parameters":[{"description":"Configuration external ID","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationShowResponse"}}},"description":"Configuration"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get a configuration by external ID","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Configuration"}},"required":["data"],"title":"ConfigurationShowResponse","type":"object"},"Configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content (key-value pairs)","type":"object"},"dynamic_content":{"additionalProperties":true,"description":"Rich content with origin metadata","nullable":true,"type":"object"},"external_id":{"description":"Configuration external identifier","type":"string"},"id":{"description":"Configuration internal ID","type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"secrets_key":{"description":"Key for secrets (null if no secrets)","nullable":true,"type":"string"},"type":{"description":"Configuration type (template name)","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","external_id","type","content"],"title":"Configuration","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Update a configuration
> Updates an existing configuration identified by its external ID.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).\
> \
> \*\*Request body:\*\*\
> \- \`configuration\` (required) – Object containing fields to update:\
> \- \`type\` (optional, string) – New configuration type.\
> \- \`content\` (optional, object) – New configuration content.\
> \
> Only the provided fields are updated; omitted fields retain their previous values. The \`external\_id\` itself cannot be modified.
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations/{external_id}":{"put":{"description":"Updates an existing configuration identified by its external ID.\n\nRequires administrative privileges (**administrator or service account**).\n\n**Request body:**\n- `configuration` (required) – Object containing fields to update:\n - `type` (optional, string) – New configuration type.\n - `content` (optional, object) – New configuration content.\n\nOnly the provided fields are updated; omitted fields retain their previous values. The `external_id` itself cannot be modified.\n","operationId":"TdCxWeb.ConfigurationController.update","parameters":[{"description":"Configuration external ID","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationUpdateRequest"}}},"description":"Configuration","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationShowResponse"}}},"description":"Updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a configuration","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationUpdateRequest":{"additionalProperties":false,"properties":{"configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content","nullable":true,"type":"object"},"type":{"description":"Configuration type","nullable":true,"type":"string"}},"type":"object"}},"required":["configuration"],"title":"ConfigurationUpdateRequest","type":"object"},"ConfigurationShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Configuration"}},"required":["data"],"title":"ConfigurationShowResponse","type":"object"},"Configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content (key-value pairs)","type":"object"},"dynamic_content":{"additionalProperties":true,"description":"Rich content with origin metadata","nullable":true,"type":"object"},"external_id":{"description":"Configuration external identifier","type":"string"},"id":{"description":"Configuration internal ID","type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"secrets_key":{"description":"Key for secrets (null if no secrets)","nullable":true,"type":"string"},"type":{"description":"Configuration type (template name)","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","external_id","type","content"],"title":"Configuration","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnprocessableEntityResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Delete a configuration
> Permanently deletes a configuration by its external ID. The deletion is immediate. There is no public API to restore a deleted configuration.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations/{external_id}":{"delete":{"description":"Permanently deletes a configuration by its external ID. The deletion is immediate. There is no public API to restore a deleted configuration.\n\nRequires administrative privileges (**administrator or service account**).\n","operationId":"TdCxWeb.ConfigurationController.delete","parameters":[{"description":"Configuration external ID","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Configuration deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete a configuration","tags":["Configurations"]}}},"components":{"schemas":{"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```
## Update a configuration
> Updates an existing configuration identified by its external ID.\
> \
> Requires administrative privileges (\*\*administrator or service account\*\*).\
> \
> \*\*Request body:\*\*\
> \- \`configuration\` (required) – Object containing fields to update:\
> \- \`type\` (optional, string) – New configuration type.\
> \- \`content\` (optional, object) – New configuration content.\
> \
> Only the provided fields are updated; omitted fields retain their previous values. The \`external\_id\` itself cannot be modified.
```json
{"openapi":"3.0.0","info":{"title":"td-cx","version":"Truedat 8.11.0"},"paths":{"/api/configurations/{external_id}":{"patch":{"description":"Updates an existing configuration identified by its external ID.\n\nRequires administrative privileges (**administrator or service account**).\n\n**Request body:**\n- `configuration` (required) – Object containing fields to update:\n - `type` (optional, string) – New configuration type.\n - `content` (optional, object) – New configuration content.\n\nOnly the provided fields are updated; omitted fields retain their previous values. The `external_id` itself cannot be modified.\n","operationId":"TdCxWeb.ConfigurationController.update (2)","parameters":[{"description":"Configuration external ID","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationUpdateRequest"}}},"description":"Configuration","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationShowResponse"}}},"description":"Updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdCxInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a configuration","tags":["Configurations"]}}},"components":{"schemas":{"ConfigurationUpdateRequest":{"additionalProperties":false,"properties":{"configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content","nullable":true,"type":"object"},"type":{"description":"Configuration type","nullable":true,"type":"string"}},"type":"object"}},"required":["configuration"],"title":"ConfigurationUpdateRequest","type":"object"},"ConfigurationShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Configuration"}},"required":["data"],"title":"ConfigurationShowResponse","type":"object"},"Configuration":{"additionalProperties":false,"properties":{"content":{"additionalProperties":true,"description":"Configuration content (key-value pairs)","type":"object"},"dynamic_content":{"additionalProperties":true,"description":"Rich content with origin metadata","nullable":true,"type":"object"},"external_id":{"description":"Configuration external identifier","type":"string"},"id":{"description":"Configuration internal ID","type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"secrets_key":{"description":"Key for secrets (null if no secrets)","nullable":true,"type":"string"},"type":{"description":"Configuration type (template name)","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","external_id","type","content"],"title":"Configuration","type":"object"},"TdCxUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnauthorizedResponse","type":"object"},"TdCxForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxForbiddenResponse","type":"object"},"TdCxUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxUnprocessableEntityResponse","type":"object"},"TdCxInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdCxInternalServerErrorResponse","type":"object"}}}}
```