diff --git a/docs/api/api-authentication.md b/docs/api/api-authentication.md new file mode 100644 index 00000000..d3e02f3e --- /dev/null +++ b/docs/api/api-authentication.md @@ -0,0 +1,55 @@ +# API Authentication + +Authenticating your protected API requests. + +Cachet is built on the belief that your service status is open and transparent, +therefore all `GET` requests are public and require no authentication to access +the information. The following are exempt from this rule: + +- Disabled components will only return in the Component API if you provide a + valid API token. +- The Subscribers API will only work if you provide a valid API token, we + don't want to expose email addresses. + +All other requests require authentication, either with `Basic Auth` or the +preferred `API Token`. + +## Basic Auth + +When making any request to the API which is not a `GET`, you'll need to use +some kind of authentication. The simplest of the authorization methods offered +by Cachet is [BasicAuth][1]. + +> **This is not secure** +> For obvious reasons, sending your authentication details in plain text is not +> secure. We do advise that you add SSL to your Cachet installation for added +> security, but suggest using API tokens. + +To authenticate your requests you only need to provide your email and password. + +``` +$ curl -u username@example.com:password -H "Content-Type: application/json" \ + -d '{"name":"API","description":"An example description","status":1}' \ + http://status.cachethq.io/api/v1/components +``` + +## API Token + +The API Token is generated at installation time for the main user or when a +new team member is added to your status page and can be found on your profile +page (click your profile picture to get there). + +Once you have your token you'll need to add a new request header of +`X-Cachet-Token: TOKEN` + +``` +$ curl -H "Content-Type: application/json;" -H "X-Cachet-Token: YOUR_KEY_HERE" \ + -d '{"name":"API","description":"An example description","status":1}' \ + http://status.cachethq.io/api/v1/components +``` + + + +[1]: http://en.wikipedia.org/wiki/Basic_access_authentication + + diff --git a/docs/api-documentation.md b/docs/api/api-documentation.md similarity index 100% rename from docs/api-documentation.md rename to docs/api/api-documentation.md diff --git a/docs/faq.md b/docs/faq.md index cfe6ab53..422487d4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -33,19 +33,42 @@ Psy Shell v0.8.8 (PHP 7.1.6 — cli) by Justin Hileman Cachet has built-in support for: -- MySQL +- MySQL/MariaDB - SQLite - PostgreSQL - SQL Server ### Can Cachet support database X? -Cachet is built on the [Laravel](https://laravel.com) framework. By default, Laravel supports the databases listed above but can be extended to support new drivers, so whilst technically possible, it's not within scope of the core team to provide support. +Cachet is built on the [Laravel](https://laravel.com) framework. By default, +Laravel supports the databases listed above but can be extended to support +new drivers, so whilst technically possible, it's not within scope of the +core team to provide support. -Each new driver requires additional support, testing and maintenance to retain compatibility with the features we want to build into Cachet in the future. +Each new driver requires additional support, testing and maintenance to +retain compatibility with the features we want to build into Cachet in the +future. ## Support and troubleshooting ### Do you offer paid support for Cachet? -We have been experimenting with paid support for Cachet at a limited scale. Cachet is not a full-time job, so our time is low and we cannot yet promise that your support request will be dealt with immediately. +We have been experimenting with paid support for Cachet at a limited scale. +Cachet is not a full-time job, so our time is low and we cannot yet +promise that your support request will be dealt with immediately. + +## Cachet usage + +### Why isn't the _Subscribe_ button enabled? + +Cachet checks some informations before displaying the _Subscribe_ button, +because checking the "Enable subscribers" is not enough. +To see the _Subscribe_ button you need to: + +- Check the box "Enable subscribers" in the settings. +- Set the `MAIL_*` option in your `.env` file. + +The second item is important, because if your mail is not well configured you +won't be able to send mails to your subscribers. + +> Note: The MAIL\_NAME **is** mandatory too, it is the sender name. diff --git a/docs/third-party-integrations.md b/docs/third-party-integrations.md new file mode 100644 index 00000000..9dd937c4 --- /dev/null +++ b/docs/third-party-integrations.md @@ -0,0 +1,30 @@ +# Third-party Integrations + +Below is a list of known applications or services using the Cachet API. + +Name|Link|Description +----|----|----------- +Cachet Monitor|[https://github.com/castawaylabs/cachet-monitor][1]|For URL monitoring. Automatic incident updates +Sensu Cachet|[https://github.com/bimlendu/sensu-cachethq][2]|Sensu handler for updating Cachet +Hubot Cachet|[https://github.com/willdurand/hubot-cachet][3]|A hubot script to manage incidents/statuses with Cachet +Nagios Notification|[https://github.com/mpellegrin/nagios-eventhandler-cachet][4]|A Nagios event handler to push Nagios notifications to Cachet API +Salt Cachet|[https://github.com/alkivi-sas/salt-cachet][5]|Salt module to use with Cachet +Pingometer|[https://pingometer.com][6]|Website uptime monitoring +Cachet URL Monitor|[https://github.com/mtakaki/cachet-url-monitor][7]/|Monitors an URL using HTTP status code, latency, and/or payload regex +Zabbix-Cachet|[https://github.com/qk4l/zabbix-cachet][8]|Synhronise your Zabbix IT Services and Cachet +CheckItOn.Us|[https://checkiton.us][9]|Server monitoring tool +Cachet-Monitor|[https://github.com/gaz492/cachet-monitor][10]|Monitors URL status via checking status codes, supports all Cloudflare http codes and more. See README for more + + +[1]: https://github.com/castawaylabs/cachet-monitor +[2]: https://github.com/bimlendu/sensu-cachethq +[3]: https://github.com/willdurand/hubot-cachet +[4]: https://github.com/mpellegrin/nagios-eventhandler-cachet +[5]: https://github.com/alkivi-sas/salt-cachet +[6]: https://pingometer.com/ +[7]: https://github.com/mtakaki/cachet-url-monitor/ +[8]: https://github.com/qk4l/zabbix-cachet +[9]: https://checkiton.us/ +[10]: https://github.com/gaz492/cachet-monitor + +