Add page on permission management.

_sidebar.md

@@ -4,6 +4,7 @@
     * [Publishing the service](getting-started/publish.md)
     * [Inspecting the logs](getting-started/inspection.md)
     * [Using custom domains](getting-started/custom-domains.md)
+    * [Managing permissions](getting-started/managing-permissions.md)
 * [Constructors](constructors/index.md)
     * [docker](constructors/docker.md)
     * [golang](constructors/golang.md)

getting-started/custom-domains.md

@@ -1,6 +1,6 @@
 # Adding custom domains
 
-Being reachable under some `*.invoke.valar.dev` domain is nice and all,
+Being reachable under some `myproject-myapp.valar.app` domain is nice and all,
 but sometimes you want to do stuff without having the valar domain branding in the way. To help you with that, we provide support for custom domains.
 
 To get started, choose a domain you have full control over. To verify ownership, you have to set specific DNS records for the domain.

getting-started/managing-permissions.md

@@ -0,0 +1,46 @@
+# Permissions
+
+The permission system unifies permission management for all Valar components, separated by a concept of namespaces. As of today, there are two of them: `service`, which manages service access and `kv`, which manages access to Valar's integrated key-value store. In these namespaces, users can assign permissions as they see fit. To manage permissions inside a specific path, you'll need to have `manage` permissions within that path.
+
+Let's walk through how to manage permissions for your project. To inspect the permissions in the scope of your project, use `valar auth list`.
+
+```bash
+$ valar auth list
+PATH              USER             ACTION STATE
+service:myproject human:anonymous  invoke allowed
+service:myproject human:myuser     invoke allowed
+service:myproject human:myuser     manage allowed
+service:myproject human:myuser     read   allowed
+service:myproject human:myuser     write  allowed
+```
+
+The command also takes an optional path parameter (which defaults to `service:myproject`). However, if you want to pre-filter based on a prefix, you could use `service:myproject/myservice`.
+
+To change these permissions, you can opt to either `allow`, `forbid` or `clear` the permissions for a specific path, user and action. While `allow` and `forbid` edit or insert existing permission entries, `clear` removes any specific entry that matches the specified criteria.
+
+```bash
+# Forbid anonymous user access to myservice
+$ valar auth forbid service:myproject/myservice human:anonymous invoke
+modified
+```
+
+To check if a specific user can perform an action, you can use `valar auth check`.
+
+```bash
+$ valar auth check service:myproject/myservice human:anonymous invoke
+forbidden
+```
+
+## Evaluation
+
+To understand how permissions are evaluted, you have to view them on a prefix-tree basis. Both paths and users act as prefix matchers, for example any path `myproject` matches `myproject/myservice` and `myproject` but not `otherproject`.
+
+Users can be matched against both `human` and `service` users. For example, if `myservice` would want to access the KV store, it wouth authenticate as `myproject/myservice`. For `service` users, the hierarchical matching applies in the exact same way as described above.
+
+On the other hand, `human` users are not hierarchical in the same way as `service` users, but they use simple subset matching.
+
+- `human:anonymous` matches any `human` user.
+- `human:authenticated` matches all except `human:anonymous`.
+- `human:myaccount` matches an exact user account with the name `myaccount`.
+
+Exact user matches take priority over `authenticated` matches, while `authenticated` takes priority over `anonymous`.