API conventions

You can interact with most nio binaries through a REST API. The API supports the standard HTTP request types of GET, POST, PUT, and DELETE. Data responses are returned in JSON format.

The REST API is available in nio binaries that include the nio REST Component. Read more about nio core components here: docs.n.io/binaries/components.html.

Authentication and authorization

Authentication is the action to verify the identity of a user or process.

Authorization is the process of giving someone permission to perform an action.

You will need to include an authorization header with your nio API requests. For examples, see Basic Auth and JWT. For examples of adding headers to curl requests, see headers.

User names and passwords are specified in the users.json file in the etc directory.

Authorization for your project's users is specified in the permissions.json file in the etc directory of your project.

If you want to secure your project and its API, change these user names and passwords and specify the permissions.

You can change the location of your users and permissions files in the [security] section of nio.conf, a YAML file.


# json configuration that defines users and their passwords - can point to a conf file

# json configuration that maps users to permissions - can point to a conf file

The default configuration is shown. You can uncomment the default configuration and it will not change. To find your users and permissions in files other than etc/users.json and etc/permissions.json, uncomment the configuration and edit it.

You can use different types of authentication, such as basic authentication and JSON Web Tokens, with the nio Platform.

Basic Authentication (Basic Auth)

When using basic authentication, the REST API requires a username and password.

To use basic auth, include a base-64 encoded version of your username:password in the Authorization header of your request. The default username:password from the project template is Admin:Admin. An example of basic authorization in your request header follows:

{ "authorization": "Basic QWRtaW46QWRtaW4=" }

For examples of adding headers to a curl request, see headers.

Adding a user example

If I wanted to add a user with username nio and password superSecretPassword, first the password needs to be to base64 encoded, which gives c3VwZXJTZWNyZXRQYXNzd29yZA==. The etc/users.json file then needs to be updated with the new username / password, which would look like:

    "Admin": {
        "password": "QWRtaW4="
    "nio": {
        "password": "c3VwZXJTZWNyZXRQYXNzd29yZA=="

Next the etc/permissions.json file would have to be updated to give that user rwx permissions.

    "Admin": {
        ".*": "rwx"
    "nio": {
        ".*": "rwx"

After saving and restarting, you will be able to authenticate to nio by using this BasicAuth:

authorization: Basic bmlvOnN1cGVyU2VjcmV0UGFzc3dvcmQ=

bmlvOnN1cGVyU2VjcmV0UGFzc3dvcmQ= is nio:superSecretPassword base64 encoded

JSON Web Tokens (JWT)

When using JSON Web Tokens (JWT), first obtain an access token, and then include it in the header.

{ "authorization": "Bearer <your token>" }

For examples of adding headers to a curl request, see Headers.

Testing with curl

To test nio API requests and responses, you can use a tool such as Postman or a curl command from your terminal. curl commands start with curl, and then include the request type, a URL, and possibly a request header and a request body. For the nio API, an authorization header is required.

Request type

Your request type will be one of GET, POST, PUT, or DELETE.

With the curl command, you can specify the request type with following options:



Your request type will be followed by a URL.

Base URL

The base of the URL for your API request is the address where your nio project is running. Obtain the base URL from your nio logs.

For a local project


For a remote project

https:// <IP address:port> /


The endpoint is added to the base URL


You can also add query parameters to the URL, but for the most part, the nio API does not use query parameters.


In your request, you need to include a header with your Basic Auth or JWT authentication. You can add auth to your curl requests with the -H header flag or the --user flag followed by a string. The following formats will work:

  -H 'authorization: Basic <base 64 encoded username:password>'

  -H 'authorization: Bearer <your token here>'

  --user 'Admin:Admin'

To send data with your request, you need to include the data's Content-Type in your header.

  -H 'Content-Type: application/json'


In the request body, if you need to include data, add body data to a curl request with the -d or --data flag.

-d '{"type": "Logger", "name": "Log"}'

--data '{"type": "Logger", "name": "Log"}'

Putting it all together

A typical curl request to the nio API incorporating all these parts follows:

curl -XPOST 'http://localhost:8181/blocks' --user 'Admin:Admin' --data '{"type": "Logger", "name": "Log"}' -H 'Content-Type: application/json'

results matching ""

    No results matching ""