From 6ef0c8e95055511feb7af49b7cee8e7888843030 Mon Sep 17 00:00:00 2001 From: Julian Lam Date: Mon, 10 May 2021 11:20:24 -0400 Subject: [PATCH] docs: update API docs to better outline authentication options --- public/openapi/read.yaml | 7 +++++++ public/openapi/write.yaml | 4 ++++ 2 files changed, 11 insertions(+) diff --git a/public/openapi/read.yaml b/public/openapi/read.yaml index f778e533e4..6605079d47 100644 --- a/public/openapi/read.yaml +++ b/public/openapi/read.yaml @@ -31,6 +31,13 @@ info: * Up until v1.14.3, this is provided by [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). The Write API plugin needs to be installed before authentication via bearer token is enabled on routes provided by the Read API. * From NodeBB v1.15.0 onwards, the Write API is available in core, and bearer authentication is available out-of-the-box + + In both cases, a bearer token is issued in the NodeBB admin panel in order to grant access to the API. + + There are two types of tokens: + * A *user token* is associated with a specific uid, and all calls made are made in the name of that user + * A *master token* is not associated with any specific uid, though a `_uid` parameter is required in the request, and then all calls are made in the name of *that* user. + This is the only difference between the two tokens. A master token with `_uid` set to a non-administrator will not allow you to make administrative calls. tags: - name: home description: Routes used at the forum index only diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml index b7d1363e1d..8bf652c3d8 100644 --- a/public/openapi/write.yaml +++ b/public/openapi/write.yaml @@ -15,6 +15,10 @@ info: Years prior to this determination, many users of NodeBB had asked for a RESTful API to call against NodeBB, which led to the creation of [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). In tandem with the above decision, the Write API was merged into NodeBB core in late 2020. v3 of the Write API (this document) achieves rough feature parity with v2 of the Write API plugin. + + # Authentication + + Please see the ["Authentication" section under the Read API](../read/#section/Overview/Authentication) for more information on how to authenticate against this API in order to make calls. version: 1.15.0 contact: email: support@nodebb.org