[doc] premonition, oauth

docs/dev/locales.md

@@ -1,9 +1,11 @@
 ---
 layout: default
-title: Support a new language
+title: Internationalization
 permalink: /dev/locales
 parent: Hacking
+nav_order: 7
 ---
 
-### Add a new locale
-watch [this commit](https://framagit.org/les/gancio/commit/cd95c7eb3b9e4bc4832a7b33d8d79b4fd3cbda2d)
+## Internationalization 
+
+We're self-hosting an instance of [weblate](https://weblate.gancio.org) you can use to help us with translations.

docs/dev/migration.md

@@ -1,11 +0,0 @@
----
-layout: default
-title: Migration
-permalink: /dev/migration
-parent: Hacking
----
-
-If you need to modify the db's structure while hacking, just change `server/api/models/` and 
-remember to create a migration, to understand how things works [check the sequelize documentation](https://sequelize.org/master/manual/migrations.html)
-
-

docs/dev/oauth.md

@@ -0,0 +1,98 @@
+---
+layout: default
+title: OAuth
+permalink: /dev/oauth
+parent: Hacking
+nav_order: 4
+---
+
+> error "BETA FEATURE"
+> Expect bad behavior and open [issues](https://framagit.org/les/gancio/issues)
+
+## OAuth
+{: .no_toc }
+An open standard for token-based authentication and authorization on the Internet.
+
+Gancio supports OAuth 2.0, an authorization framework described in [RFC 6749](https://tools.ietf.org/html/rfc6749) that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.
+
+To obtain an OAuth token for a Gancio instance, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret](#create-client) and then proceed with normal OAuth 2.
+
+---
+
+## Create client
+Create a new application to obtain OAuth2 credentials.
+
+POST
+{: .label .label-yellow }
+`/api/client`
+
+
+#### Request parameters
+
+| client_name | `string` | A name for your application |
+| redirect_uris | `string` | Where the user should be redirected after authorization |
+| scopes | `string` | Space separated list of scopes. If none is provided, defaults to `event:write` as it's the only supported scope!|
+| website | `string` | A URL to the homepage of your app |
+
+#### Example
+```bash
+curl -X POST \
+        -d 'client_name=Wordpress Event Manager' \
+        -d 'redirect_uris=https://noblogs.org/' \
+        -d 'website=https://myapp.example' \
+        http://localhost:13120/api/client
+```
+
+#### Returns
+Application, with `client_id` and `client_secret`
+
+```json
+{
+   "name" : "Wordpress Event Manager",
+   "scopes" : "event:write",
+   "website" : "https://myapp.example",
+   "client_secret" : "909029fa12797e6bdfb5baf5e379675dfa4e3ad4",
+   "redirect_uris" : "https://noblogs.org",
+   "client_id" : "0f377e34b2aaf517f7db534f32d26b0dd938fb6d"
+}
+```
+
+#### List of scopes
+- `event:write`  
+Grant access to add/update events.
+
+## Authorize a user
+Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`. 
+The authorization code can be used while requesting a token to obtain access to user-level methods.
+
+[![assets/thumbs/oauth_auth.png](assets/thumbs/oauth_auth.png)](assets/oauth_auth.png){: data-fancybox="group" data-caption="OAuth authorization form"}
+
+
+GET
+{: .label .label-green}
+`/authorize`
+
+#### Request parameters
+
+| response_type | `string` | Should be set equal to `code` |
+| redirect_uri | `string` | Where the user should be redirected after authorization |
+| scope | `string` | Should be `event:write`|
+| client_id | `string` | `client_id`, obtained during app registration. |
+
+
+## Obtain a token
+
+POST
+{: .label .label-yellow }
+`/oauth/token`
+
+
+#### Request parameters
+
+| client_id | `string` | `client_id` obtained during [client registration](#create-client) |
+| client_secret | `string` | `client_secret` obtained during [client registration](#create-client) |
+| scope | `string` | Should be `event:write`|
+| grant_type | `string` | Set equal to `authorization_code` |
+| code | `string` | A user authorization code, obtained via [/authorize](#authorize-a-user) |
+
+

docs/dev/structure.md

@@ -3,6 +3,7 @@ layout: default
 title: Project Structure
 permalink: /dev/structure
 parent: Hacking
+nav_order: 1
 ---
 
 ### Project structure