Update Arduino en Account APIs

Author: FokkeZB

_includes/current/arduino.md

@@ -11,6 +11,7 @@ sections:
 redirect_from:
  - /refactor/arduino/
  - /v2-preview/arduino/
+ - /arduino/
 ---
 
 [Arduino](https://www.arduino.cc/en/Guide/Introduction) is an open-source electronics platform based on easy-to-use hardware and software. It's intended for anyone making interactive projects.

_includes/current/arduino/_api.md

@@ -41,7 +41,7 @@ Total airtime: 0.00 s
 See the [DeviceInfo](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/DeviceInfo/DeviceInfo.ino) example.
 
 ## Method: onMessage
-Sets a function which will be called to process incoming messages.
+Sets a function which will be called to process incoming messages. You'll want to do this in your `setup()` function and then define a `void (*cb)(const byte* payload, size_t length, port_t port)` function somewhere else in your sketch.
 
 ```c
 void onMessage(void (*cb)(const byte* payload, size_t length, port_t port));
@@ -98,7 +98,7 @@ int8_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confi
 - `const byte* payload `: Bytes to send.
 - `size_t length`: The number of bytes. Use `sizeof(payload)` to get it.
 - `port_t port = 1`: The port to address. Defaults to `1`.
-- `bool confirm = false`: Whether to ask for confirmation. Defaults to `false`.
+- `bool confirm = false`: Whether to ask for confirmation. Defaults to `false`. If confirmation fails, the method will return error code `-10`.
 
 Returns a success or error code and logs the related error message:
 
@@ -134,4 +134,4 @@ bool provision(const char *appEui, const char *appKey);
 ```
 
 - `const char *appEui`: Application Identifier for the device.
-- `const char *appKey`: Application Key assigned to the device.
+- `const char *appKey`: Application Key assigned to the device.

_includes/draft/account/_api.md

@@ -10,7 +10,6 @@ to be able to run a TTN backend.
 
 ### Security
 ---
-
 |oauth2|*OAuth 2.0*|
 |---|---|
 |Flow|accessCode|
@@ -39,7 +38,6 @@ to be able to run a TTN backend.
 
 ### /applications
 ---
-
 ##### ***GET***
 **Summary:** List applications.
 
@@ -74,7 +72,6 @@ collaborator.
 
 ### /{app_id}
 ---
-
 ##### ***GET***
 **Summary:** Get application.
 
@@ -131,7 +128,6 @@ collaborator.
 
 ### /{app_id}/euis
 ---
-
 ##### ***GET***
 **Summary:** List EUIs of an application.
 
@@ -168,7 +164,6 @@ collaborator.
 
 ### /{app_id}/euis/{eui}
 ---
-
 ##### ***PUT***
 **Summary:** Add an EUI to the application.
 
@@ -207,7 +202,6 @@ collaborator.
 
 ### /{app_id}/collaborators
 ---
-
 ##### ***GET***
 **Summary:** List the collaborators of the application.
 
@@ -227,7 +221,6 @@ collaborator.
 
 ### /{app_id}/collaborators/{username}
 ---
-
 ##### ***GET***
 **Summary:** Get a collaborators rights to the application.
 
@@ -284,7 +277,6 @@ It is not possible to
 
 ### /{app_id}/rights
 ---
-
 ##### ***GET***
 **Summary:** Get the rights you have to the specified application with the current authentication method.
 
@@ -300,9 +292,54 @@ It is not possible to
 | ---- | ----------- |
 | 200 | The rights you have to the application. |
 
-### /{app_id}/token
+### /{app_id}/access-keys
 ---
+##### ***POST***
+**Summary:** Create a new access key with the specified name and rights
+
+**Parameters**
 
+| Name | Located in | Description | Required | Type |
+| ---- | ---------- | ----------- | -------- | ---- |
+| app_id | path | The ID of the application. | Yes | string |
+| token_exchange | body | The body of the request to create an access key | No |  |
+
+### /{app_id}/access-keys/{keyname}
+---
+##### ***GET***
+**Summary:** Get information about an app access key
+
+**Parameters**
+
+| Name | Located in | Description | Required | Type |
+| ---- | ---------- | ----------- | -------- | ---- |
+| app_id | path | The ID of the application. | Yes | string |
+| keyname | path | The name of the access key | Yes | string |
+
+**Responses**
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | The resulting access key |
+
+##### ***DELETE***
+**Summary:** Remove an access key
+
+**Parameters**
+
+| Name | Located in | Description | Required | Type |
+| ---- | ---------- | ----------- | -------- | ---- |
+| app_id | path | The ID of the application. | Yes | string |
+| keyname | path | The name of the access key | Yes | string |
+
+**Responses**
+
+| Code | Description |
+| ---- | ----------- |
+| 204 | The key was successfully removed |
+
+### /{app_id}/token
+---
 ##### ***POST***
 **Summary:** Exchange an application Access Key for an application Access Token.
 

_includes/draft/account/_authentication.md

@@ -253,7 +253,7 @@ It works exactly like a standard OAuth 2.0 password flow. The client initiates a
 request:
 
 ```plaintext
-HTTP/1.1  GET /api/v2/applications/token
+HTTP/1.1  POST /api/v2/applications/token
 Content-Type: application/json
 Authorization: Basic <basic_auth>
 
@@ -306,5 +306,57 @@ If the exchange fails for whatever reason, you will get a response like this:
 }
 ```
 
+# OAuth 2.0 Authorization flow
+
+In this section we describe a sample `authorization_code` code flow.
+Assuming you have a registered client with these properties:
+
+```
+client_id: foo-client 
+client_secret: secret
+redirect_uri: http://www.example.com/oauth/callback
+scope: [ 'apps' ]
+```
+
+## 1. Make an authorization request
+
+To be able to use your client, a user will have to authorize it first on the
+account server.  You can tell the user to do so by redirecting to:
+
+```
+https://account.thethingsnetwork.org/users/authorize?client_id=foo-client&redirect_uri=http://www.example.com/oauth/callback&response_type=code
+```
+
+This will ask the user to log in and presents her with a form to authorize your
+client.  If the user authorizes your client, she will be redirected to:
+
+```
+http://www.example.com/oauth/callback?code=<auth code>
+```
+
+You need the `<auth code>` from this redirect to go to step 2.
+
+The preference of the user will be stored so this authorization step will
+redirect immediatly (without showing the form) the next time you do this for the
+same user.
+
+
+## 2. Get the access token 
+To get the access token perform the following request:
+```plaintext
+HTTP/1.1 POST /users/token
+Content-Type: application/json
+Authorization: Basic <basic_auth>
+
+{
+  "grant_type": "authorization_code",
+  "code": "<auth code>",
+  "redirect_uri: "http://www.example.com/oauth/callback"
+}
+```
+
+Where `<basic_auth>` is the basic auth digest for your client (`client_id` and
+`client_secret`) and `<auth_code>` is the authorization code received from step 1.
 
 [jwt]: https://jwt.io
+

_scripts/pull.js

@@ -76,7 +76,10 @@ if (process.env.GITHUB_OAUTH_TOKEN) {
     branch: 'v2-preview',
     path: 'apidocs.md',
     token: process.env.GITHUB_OAUTH_TOKEN,
-    file: '_includes/draft/account/_api.md'
+    file: '_includes/draft/account/_api.md',
+    replace: [
+      [/^The Things Network Account Server API/m, 'API Reference']
+    ]
   }, {
     owner: 'TheThingsIndustries',
     repo: 'node-ttn-oauth2',