diff --git a/README.md b/README.md
index 4d18e2a..3ff9076 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,54 @@
 # ungleich-otp
 
-The ungleich OTP service
\ No newline at end of file
+The ungleich OTP service that allows you access to the ungleich micro
+service infrastructure.
+
+We are using
+
+- nameko for internal communication
+- django for the DB + admin interface
+
+## Usage: WEB
+
+- No user interface (UI) supported (?)
+  -> idea is to keep flow logic in ungleich-dynamicweb
+
+## Usage: BUS and REST
+
+- BUS: send
+- Authentication
+- Use an existing token to connect to the service
+- All REST based messages: JSON
+
+### POST /app/register
+
+Register a new app. Returns an app ID.
+
+### GET /app
+
+List all registered apps for the current user.
+
+
+### GET /app/<id>
+
+Get seed for APP to be used as a token
+
+
+## Usage: OTP
+
+The seeds that you receive can be used for TOTP to authenticate your
+apps.
+
+
+## Database
+
+The database saves a list of appids with their seeds and the user
+assignments as well as whether the appid might use the BUS interface.
+
+Fields:
+
+- appname (name chosen by the user)
+- appid (a random UUID)
+- seed  (a random base32 string)
+- username (who this appid belongs to)
+- trusted (boolean, whether app is allowed to use the BUS)