website/docs: add docs for websocket connections

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>

website/developer-docs/api/api.md

@@ -0,0 +1,11 @@
+---
+title: API
+---
+
+Starting with 2021.3.5, every authentik instance has a built-in API browser, which can be accessed at https://authentik.company/api/v2beta/.
+
+To generate an API client, you can use the OpenAPI v3 schema at https://authentik.company/api/v2beta/schema/.
+
+While testing, the API requests are authenticated by your browser session.
+
+To send an API request from outside the browser, you need to set the `Authorization` Header to `Bearer <your token>`.

website/developer-docs/api/flow-executor.md

@@ -0,0 +1,72 @@
+---
+title: Flow executor
+---
+
+A big focus of authentik is the flows system, which allows you to combine and build complex conditional processes using stages and policies. Normally, these flows are executed in the browser using the authentik inbuilt flow executor (/if/flows).
+
+However, any flow can be executed via an API from anywhere, in fact that is what the Web flow executor does. This means, you can, with a few requests, execute flows from anywhere, and integrate authentik even better.
+
+:::info
+Because the flow executor stores its state in the HTTP Session, so you need to ensure cookies between flow executor requests are persisted.
+:::
+
+The main endpoint for flow execution is `/api/v2beta/flows/executor/:slug`.
+
+This endpoint accepts a query parameter called `query`, in which the flow executor sends the full Query-string.
+
+To initiate a new flow, execute a GET request.
+
+## `GET /api/v2beta/flows/executor/test-flow/`
+
+Below is the response, for example for an Identification stage.
+
+```json
+{
+    "type": "native", // Stage type, can be "native", "shell" or "redirect"
+    "flow_info": {
+        // Related flow information, mostly used for UI and surrounding elements
+        "title": "Welcome to authentik",
+        "background": "/static/dist/assets/images/flow_background.jpg",
+        "cancel_url": "/flows/-/cancel/"
+    },
+    // Main component to distinguish which stage is currently active
+    "component": "ak-stage-identification",
+
+    // Stage-specific fields
+    "user_fields": [
+        "username",
+        "email"
+    ],
+    "password_fields": false,
+    "primary_action": "Log in",
+    "sources": []
+}
+```
+
+To respond to this challenge, send a response:
+
+## `POST /api/v2beta/flows/executor/test-flow/`
+
+With this body
+
+```json
+{
+    // Component is required to determine how to parse the response
+    "component": "ak-stage-identification",
+
+    // Stage-specific fields
+    "uid_field": "jens"
+}
+```
+
+Depending on the flow, you'll either get a 200 Response with another challenge, or a 302 redirect, which should be followed.
+
+Depending also on the stage, a response might take longer to be returned (especially with the Duo Authenticator validation).
+
+To see the data layout for every stage possible, see the [API Browser](https://goauthentik.io/api/#get-/api/v2beta/flows/executor/-flow_slug-/)
+
+## Result
+
+If a stage with the component `ak-stage-access-denied` is returned, the flow has been denied.
+
+If a stage with the component `xak-flow-redirect` is returned, the flow has been executed successfully.

website/developer-docs/api/making-schema-changes.md

@@ -0,0 +1,23 @@
+---
+title: Making schema changes
+---
+
+Some backend changes might require new/different fields or remove other fields. To create a new schema after changing a Serializer, run `make gen-build`.
+
+This will update the `schema.yml` file in the root of the repository.
+
+## Building the Go Client
+
+The Go client is used by the Outpost to communicate with the backend authentik server. To build the go client, run `make gen-outpost`.
+
+The generated files are stored in `/api` in the root of the repository.
+
+## Building the Web Client
+
+The web client is used by the web-interface and web-FlowExecutor to communicate with authentik. To build the client, run `make gen-web`.
+
+Since the client is normally distributed as an npm package, running `make gen-web` will overwrite the locally installed client with the newly built one.
+
+:::warning
+Running `npm i` in the `/web` folder after using `make gen-web` will overwrite the custom client and revert to the upstream client.
+:::

website/developer-docs/api/websocket.md

@@ -0,0 +1,48 @@
+---
+title: Websocket API
+---
+
+authentik has two different WebSocket endpoints, one is used for web-based clients to get real-time updates, and the other is used for outposts to report their healthiness.
+
+
+### Web `/ws/client/`
+
+:::info
+Authentication is done using the session, so make sure to send the `Cookie` header.
+:::
+
+All messages have a common field called `message_type` to discern the type of message.
+
+#### `message` type:
+
+This type is used when the backend has a notice to show to the user. A full payload looks like:
+
+```json
+{
+    "message_type": "message",
+    "level": "error" | "warning" | "success" | "info",
+    "tags": "",
+    "message": "a message",
+}
+```
+
+### Outpost `/ws/outpost/<outpost-uuid>/`
+
+:::info
+Authentication is done via the `Authorization` header, same as the regular API. You must send a valid token with a `Bearer ` prefix.
+:::
+
+All messages have two fields, `instruction` and `args`. Instruction is any number from this list:
+
+- `0`: ACK, simply acknowledges the previous message
+- `1`: HELLO, used for monitoring and regularly sent by outposts
+- `2`: TRIGGER_UPDATE, sent by authentik to trigger a reload of the configuration
+
+Arguments for these messages vary, all though these common args are always sent:
+
+- `args['uuid']`: A unique UUID generated on startup of an outpost, used to uniquely identify it.
+
+These fields are only sent for HELLO instructions:
+
+- `args['version']`: Version of the outpost
+- `args['buildHash']`: Build hash of the outpost, when available