1 line
110 KiB
JSON
1 line
110 KiB
JSON
|
{"openapi":"3.1.1","info":{"title":"KeyHelp RESTful API","version":"2.15","description":"Provides an interface to a server managed by the KeyHelp Server Control Panel.\n\nThe latest version of this documentation is available <a href=\"https://api.keyhelp.de\" target=\"_blank\">here</a>.\n\n## URL\n* To communicate with the API, you need to call a specific URL which looks like this:<br>\n ```\n https://<hostname>/api/v2/<API endpoint>\n https://<IP address>/api/v2/<API endpoint>\n ```\n* Have a look below to see all available API endpoints.\n\n## Authentication\n* You need to define API keys inside of the KeyHelp user interface (*Admin area* -> *Configuration* -> *API*).<br>\n Each API key should be restricted to certain IP / IP range.\n* Pass the API key with each request using the `X-API-Key` header field.\n\n## Request format\n* Some requests require you to send data inside of the request body.<br>\n These data must be sent as `application/json`.\n\n## Response format\n* Use the `ACCEPT` header field to specify your desired response mime type.\n* The following response formats are supported:\n - `application/json` (default)\n - `application/xml`\n - `text/yaml`\n\n## Hints\n* The API is not enabled by default. You first have to turn it on via KeyHelp user interface.<br>\n (*Admin area* -> *Configuration* -> *API*)\n* You can define how the API should react in certain cases, for this purpose you might want to have a look at the API options.<br>\n (*Admin area* -> *Configuration* -> *API* -> *Options*)\n* You can turn on the `password_hash` field in API settings, and so read and set the password hash of a given element.<br>\nWhen using this field, make sure that you always use the same hash algorithm that KeyHelp uses, otherwise full functionality cannot be guaranteed. If using the `password_hash` field in `[POST/PUT] /clients/` the additional `password_hash_os` field is required.\n* KeyHelp performs a webserver reload every time it is necessary. This can either be triggered by your customers using the KeyHelp UI or a previous API request. Your API client will receive a `500`/`503` error if it sends the request right in the moment of the reload. You have to ensure, your API client can handle such situations, for example by sending the request again after a few seconds.\n* Some object schemas contain a read-only \"status\" field. The meaning of these values is as follows:<br>\n * `0` = `unknown`\n * `1` = `okay`\n * `2` = `error`\n * `3` = `config_new`\n * `4` = `config_update`\n\n## Shorthand byte values\n* When specifying byte values, you can also use a shorthand notation.\n* Available options are: `K` (kilobyte), `M` (megabyte), `G` (gigabyte), `T` (terabyte), `P` (petabyte)\n* One kilobyte is described as 1024 byte, 1M equals to 1048576 bytes.\n* Do not use decimals, only integers!\n\n## HTTP status code summary\n| Code | Description |\n| --- | --- |\n| **200 - OK** | Everything worked as expected. |\n| **201 - Created** | The resource was successfully created. |\n| **202 - Accepted** | The request has been received and is handled asynchronously. |\n| **204 - No Content** | The response does not contain any data. Used on delete operations. |\n| **400 - Bad Request** | The request was unacceptable due to a malformed request, invalid parameter value or a missing required parameter. |\n| **401 - Unauthorized** | Invalid API key provided. |\n| **403 - Forbidden** | API access is denied. |\n| **404 - Not Found** | The resource was not found / The requested endpoint was not found. |\n| **405 - Method Not Allowed** | The HTTP method for the requested endpoint is not allowed. |\n| **406 - Not Acceptable** | Invalid Accept header value. Mime type not supported. |\n| **5xx - Server error** | Something went wrong on KeyHelp's end. |\n\n## API version upgrade guide\n #### Breaking changes from `v1` to `v2`\n 1) `[GET] /certificates/`: Output format changed for field `components`.\n 2) `[PUT/POST] /certificates/`: Certificate components are now specified within the `components` field.\n","contact":{"name":"Alex
|