> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/finger/technical_documentation/api_reference/management/update-the-runtime-configuration.md).

# Update the runtime configuration

Updates the service configuration in memory. The `config_json_string` field contains the parameters to change, serialized as a JSON string; the parameters that are not included keep their value.

Not every parameter returned by `GET /api/v1/finger/config` can be changed with this endpoint:

| Parameter                               | Access         |
| --------------------------------------- | -------------- |
| `engine_url`                            | Read and write |
| `engine_connection_timeout`             | Read and write |
| `engine_request_timeout`                | Read and write |
| `engine_max_retries`                    | Read and write |
| `engine_retry_delay`                    | Read and write |
| `engine_verify_ssl`                     | Read and write |
| `engine_verbose`                        | Read and write |
| `metrics_saturation_queue_p95_ms`       | Read and write |
| `metrics_saturation_min_inflight_ratio` | Read and write |
| `metrics_error_rate_warning`            | Read and write |
| `metrics_idle_rps_threshold`            | Read and write |
| `metrics_quality_alert_window_seconds`  | Read and write |
| `port`                                  | Read only      |
| `number_of_threads`                     | Read only      |
| `connection_timeout`                    | Read only      |
| `keep_alive_request_number`             | Read only      |
| `client_max_body_size`                  | Read only      |
| `logger_path`                           | Read only      |
| `logger_file_prefix`                    | Read only      |
| `logger_level`                          | Read only      |
| `logger_rotation`                       | Read only      |
| `logger_max_files`                      | Read only      |
| `metrics_enabled`                       | Read only      |
| `engine_pool_size`                      | Read only      |
| `auth_*`                                | Rejected       |

* Read and write parameters are applied without restarting the service. When the equivalent environment variable is set (for example `FACEPHI_FINGER_ENGINE_REQ_TIMEOUT` or `FACEPHI_FINGER_REST_METRICS_ERROR_RATE_WARNING`), its value prevails over the one sent.
* The read and write `engine_*` parameters are only applied on `master` nodes; `worker` nodes accept them without effect.
* The `metrics_*` parameters are the thresholds `GET /api/v1/finger/metrics` uses to classify the service state and raise alerts. An invalid or negative value is discarded with a warning in the log and the previous source in the precedence order is used.
* Read only parameters are only configured at startup, through `config.json` or environment variables. If they are sent to this endpoint, the request answers `200` and `GET` returns the value sent, but the service keeps using the value it started with.
* Changes are not saved to `config.json` and are lost when the service restarts.
* JWT authentication settings (`auth_*`) are startup only: `GET` never returns them and this endpoint rejects any request that includes them with HTTP `400` and `message` equal to `JWT auth settings are not accessible from the config endpoint`.

Errors:

| HTTP  | Detail                                                                                                                 | Cause                                                                                        |
| ----- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `400` | `Key config_json_string not found`, `Key config_json_string is not a string`, `Key config_json_string is empty string` | `config_json_string` is missing, is not a string or is empty                                 |
| `400` | `JWT auth settings are not accessible from the config endpoint`                                                        | `config_json_string` includes `auth_*` settings                                              |
| `500` | `Failed to load configuration from config_json_string`                                                                 | `config_json_string` does not contain a valid JSON object; the configuration does not change |

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"tags":[{"name":"Management","description":"Version, health, operational metrics and runtime configuration of the service."}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"HS256 JWT signed with `auth_jwt_secret` and carrying an `exp` claim, sent as `Authorization: Bearer <jwt>`.\nAccepted while `auth_accept_authorization_header` is `true` (default). Only enforced when `auth_enabled` is\n`true`.\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT, sent as is (without the `Bearer` prefix) in the header named by `auth_api_key_header_name`\n(`x-api-key` by default). Accepted while `auth_accept_api_key_header` is `true` (default). Only enforced when\n`auth_enabled` is `true`.\n"}},"schemas":{"ConfigUpdateRequest":{"type":"object","required":["config_json_string"],"properties":{"config_json_string":{"type":"string","description":"Parameters to change, serialized as a JSON object inside a string. Parameters that are not included keep\ntheir current value. JWT authentication settings (`auth_*`) are rejected.\n"}}},"MessageResult":{"type":"object","properties":{"message":{"type":"string","description":"Service message."}},"required":["message"]},"BadRequestResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."},"UnauthorizedResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"ExceptionResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"exception":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","exception","timeStamp"]}},"responses":{"BadRequest":{"description":"The request is invalid or could not be processed. `message` carries the reason; see the operation\ndescription for the values it can take.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"Unauthorized":{"description":"JWT authentication is enabled and the request carries no token or an invalid one. `message` is one of\n`Missing authentication token`, `JWT token is expired`, `JWT token does not include exp claim`,\n`JWT token validation failed` or, when `auth_jwt_secret` is empty, `Authentication secret is not configured`.\n","headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}},"InternalError":{"description":"Unhandled internal error. `exception` carries the detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer` on `401` responses.","schema":{"type":"string"}}}},"paths":{"/api/v1/finger/config":{"post":{"summary":"Update the runtime configuration","description":"Updates the service configuration in memory. The `config_json_string` field contains the parameters to\nchange, serialized as a JSON string; the parameters that are not included keep their value.\n\nNot every parameter returned by `GET /api/v1/finger/config` can be changed with this endpoint:\n\n| Parameter | Access |\n|---|---|\n| `engine_url` | Read and write |\n| `engine_connection_timeout` | Read and write |\n| `engine_request_timeout` | Read and write |\n| `engine_max_retries` | Read and write |\n| `engine_retry_delay` | Read and write |\n| `engine_verify_ssl` | Read and write |\n| `engine_verbose` | Read and write |\n| `metrics_saturation_queue_p95_ms` | Read and write |\n| `metrics_saturation_min_inflight_ratio` | Read and write |\n| `metrics_error_rate_warning` | Read and write |\n| `metrics_idle_rps_threshold` | Read and write |\n| `metrics_quality_alert_window_seconds` | Read and write |\n| `port` | Read only |\n| `number_of_threads` | Read only |\n| `connection_timeout` | Read only |\n| `keep_alive_request_number` | Read only |\n| `client_max_body_size` | Read only |\n| `logger_path` | Read only |\n| `logger_file_prefix` | Read only |\n| `logger_level` | Read only |\n| `logger_rotation` | Read only |\n| `logger_max_files` | Read only |\n| `metrics_enabled` | Read only |\n| `engine_pool_size` | Read only |\n| `auth_*` | Rejected |\n\n- Read and write parameters are applied without restarting the service. When the equivalent environment\n  variable is set (for example `FACEPHI_FINGER_ENGINE_REQ_TIMEOUT` or\n  `FACEPHI_FINGER_REST_METRICS_ERROR_RATE_WARNING`), its value prevails over the one sent.\n- The read and write `engine_*` parameters are only applied on `master` nodes; `worker` nodes accept them\n  without effect.\n- The `metrics_*` parameters are the thresholds `GET /api/v1/finger/metrics` uses to classify the service\n  state and raise alerts. An invalid or negative value is discarded with a warning in the log and the\n  previous source in the precedence order is used.\n- Read only parameters are only configured at startup, through `config.json` or environment variables. If\n  they are sent to this endpoint, the request answers `200` and `GET` returns the value sent, but the service\n  keeps using the value it started with.\n- Changes are not saved to `config.json` and are lost when the service restarts.\n- JWT authentication settings (`auth_*`) are startup only: `GET` never returns them and this endpoint\n  rejects any request that includes them with HTTP `400` and `message` equal to\n  `JWT auth settings are not accessible from the config endpoint`.\n\nErrors:\n\n| HTTP | Detail | Cause |\n|---|---|---|\n| `400` | `Key config_json_string not found`, `Key config_json_string is not a string`, `Key config_json_string is empty string` | `config_json_string` is missing, is not a string or is empty |\n| `400` | `JWT auth settings are not accessible from the config endpoint` | `config_json_string` includes `auth_*` settings |\n| `500` | `Failed to load configuration from config_json_string` | `config_json_string` does not contain a valid JSON object; the configuration does not change |\n","operationId":"updateConfig","tags":["Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateRequest"}}}},"responses":{"200":{"description":"Configuration updated successfully (`Configuration updated successfully`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```