diff --git a/README.md b/README.md
index b5f7b1c..9b76c49 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,62 @@
 # Light OpenID
-Lightweight OpenID primitives & client
+[![Build Status](https://drone.communiquons.org/api/badges/pierre/light-openid/status.svg)](https://drone.communiquons.org/pierre/light-openid)
+[![Crate](https://img.shields.io/crates/v/light-openid.svg)](https://crates.io/crates/light-openid)
+
+Lightweight OpenID primitives & client. This package can be used to turn an application into an OpenID relying party.
+
+> **Warning !** This crate has not been audited, use at your own risks!
+> 
+> It is your responsibility to implement the routes (start & finish authentication) that interacts
+> with the `OpenIDConfig` helper structure.
+> 
+> Moreover, only a very small subset of OpenID specifications are supported :
+> * `code` authorization flow
+> * The scopes `openid profile email` are hard coded and cannot be changed
+> * User info retrieval using `userinfo` endpoint
+
+## Basic usage
+```rust
+let config = OpenIDConfig::load_from_url(&AppConfig::get().configuration_url).await.unwrap();
+
+// Start authentication
+let auth_url = config.gen_authorization_url("client_id", "state", "redirect_uri");
+redirect_user(auth_url);
+
+
+// Finish authentication
+let token_response = config.request_token("client_id", "client_secret", "code", "redirect_uri").await.unwrap();
+let user_info = config.request_user_info(&token_response).await.unwrap();
+// user_info now contains profile info of user
+```
+
+
+## Feature `crypto-wrapper`
+`CryptoWrapper` is a helper that can encrypt to base64-encoded string structures:
+
+```rust
+#[derive(Encode, Decode, Eq, PartialEq, Debug)]
+struct Message(String);
+
+fun test() {
+    let wrapper = CryptoWrapper::new_random();
+    let msg = Message("Hello world".to_string());
+    let enc = wrapper.encrypt(&msg).unwrap();
+    let dec: Message = wrapper.decrypt( & enc).unwrap();
+    
+    assert_eq!(dec, msg);
+}
+```
+
+`BasicStateManager` is a helper that uses `CryptoWrapper` to generate and validates states for OpenID authentication:
+
+```rust
+let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1));
+let manager = BasicStateManager::new();
+let state = manager.gen_state(ip).unwrap();
+assert!(manager.validate_state(ip, &state).is_ok());
+```
+
+
+## Complete example
+A complete example usage of this crate can be found here: 
+[https://gitea.communiquons.org/pierre/oidc-test-client](https://gitea.communiquons.org/pierre/oidc-test-client)
\ No newline at end of file