Document API authentication and apps API

docs/API.md

@@ -1,3 +1,36 @@
+# API documentation
+
+## Getting an API token
+
+To get access to the API, you should register your app and obtain a
+token. To do so, use the `apps` API (accessible without a token) to create
+a new app. Store the result somewhere for future use.
+
+Then send a request to `/api/v1/oauth2`, with the following GET parameters:
+
+- `client_id`, your client ID.
+- `client_secret`, your client secret.
+- `scopes`, the scopes you want to access. They are separated by `+`, and can either
+be `read` (global read), `write` (global write), `read:SCOPE` (read only in `SCOPE`),
+or `write:SCOPE` (write only in `SCOPE`).
+- `username` the username (not the email, display name nor the fully qualified name) of the
+user using your app.
+- `password`, the password of the user.
+
+Plume will respond with something similar to:
+
+```json
+{
+  "token": "<YOUR TOKEN HERE>"
+}
+```
+
+To authenticate your requests you should put this token in the `Authorization` header:
+
+```
+Authorization: Bearer <YOUR TOKEN HERE>
+```
+
 <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
 
 <div id="api"></div>

docs/api.yaml

@@ -10,6 +10,10 @@ servers:
     description: Demo instance
 
 paths:
+  /apps:
+    post:
+      description:
+        Registers an application.
   /posts/{id}:
     get:
       description:
@@ -27,6 +31,21 @@ paths:
         List posts.
 
 definitions:
+  App:
+    type: "object"
+    properties:
+      name:
+        type: "string"
+        example: "My app"
+      website:
+        type: "string"
+        example: "https://my.app"
+      client_id:
+        type: "string"
+        example: "My app"
+      client_secret:
+        type: "string"
+        example: "My app"
   Post:
     type: "object"
     properties: