diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4c4ee7d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+
+# authd
+
+authd is a token-based authentication micro-service.
+
+## Build
+
+`authd` is written in Crystal and uses `build.zsh` as Makefile generator, as
+well as shards to fetch dependencies.
+
+You’ll need the following tools to build authd:
+
+  - crystal
+  - shards
+  - build.zsh
+  - make
+
+To build authd, run the following commands:
+
+```
+shards install
+make
+```
+
+Note that if you clone authd from its repository, its `Makefile` may be missing.
+In such situations, run `build.zsh -c` to generate it, after which `make` should run fine.
+
+## Deployment
+
+```
+$ authd --help
+usage: authd [options]
+    -s directory, --storage directory
+                                     Directory in which to store users.
+    -K file, --key-file file         JWT key file
+    -R                               --allow-registrations
+    -h, --help                       Show this help
+$
+```
+
+### Users storage
+
+The storage directory will default to `./storage`.
+
+No SQL database, database management system or other kind of setup is required to run authd and store users.
+
+To migrate an instance of authd, a simple copy of the storage directory will be enough.
+Make sure your copy preserves symlinks, as those are extensively used.
+
+### Administrating users
+
+The `authd-user-add` and `authd-user-allow` are tools to add users to authd’s database and to edit their permissions.
+
+The permission level `none` can be used in `authd-user-allow` to remove a permission.
+
+### Key file
+
+authd will provide users with cryptographically signed tokens.
+To sign and check those tokens, a shared key is required between authd and services using authd.
+
+authd reads that key from a file to prevent it being visible on the command line when running authd.
+
+Any content is acceptable as a key file.
+
+Example:
+
+```
+$ echo "I am a key." > key-file
+$ authd -K ./key-file
+```
+
+## APIs
+
+### Protocol
+
+authd’s protocol is still subject to change.
+
+### Libraries
+
+A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal.
+
+```crystal
+require "authd"
+
+authd = AuthD::Client.new
+authd.key = File.read("./some-file").chomp
+
+pp! r = authd.get_token?("login", "password")
+
+pp! r = authd.add_user("login", "password")
+
+pp! u = authd.get_user?("login", "password").not_nil!
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+