nodebb-plugin-open-api v1.1.3

Open API

This plugin exposes a API interface for NodeBB. It is useful if you would like to supplment the built-in read-only API, in order to push items/actions/events to NodeBB.

With this plugin, however, you can create content on NodeBB externally (new topics, new posts, etc), which comes in handy when third-party applications want deeper integration with NodeBB.

Installation

Install this plugin via the plugins page in the ACP.

API Resources

• api/v1 Endpoints

Quick Start

1. Install and activate the plugin, reload NodeBB
2. Generate your uid an API token in the ACP page
3. curl -H "Authorization: Bearer {YOUR_TOKEN}" --data "title={TITLE}&content={CONTENT}&cid={CID}" http://localhost:4567/api/v1/topics

Authentication

Authentication is handled either via HTTP Bearer Token or JSON Web Token, as generated/specified in the Open API.

Bearer Tokens

• 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.A master token with _uid set to a non-administrator will not allow you to make administrative calls.

Note: The first token must be generated via the administration page (admin/plugins/open-api), but additional user tokens can be generated using an existing user/master token.

JSON Web Tokens

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

To make requests with a JSON Web Token instead of a user/master token, sign the entire request payload with the same secret as defined in the plugin, and either send it in the POST body, or as a query string parameter. In both cases, the key token is used.

Error Handling

When the API encounters an error, it will do it's best to report what went wrong. Errors will follow the format specified in this example:

{
    "code": "not-authorised",
    "message": "You are not authorised to make this call",
    "params": {}
}