Skip to content

NeuroScale Platform API v1

The NeuroScale Platform is an ecosystem for developing and deploying scalable Brain Computer Interface (BCI) applications in the Cloud.

Introduction

The NeuroScale Platform API is organized around REST. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

Authentication

Every API request must include a valid access token (unless stated otherwise). The access token identifies the entity on whose behalf the request is being made and is used to check that they have permission to access the requested resource.

Generating Access Tokens

The NeuroScale Platform API uses bearer tokens [RFC 6750] to control access to protected resources. Currently, access tokens generated by the NeuroScale Platform API do not expire (though this may change in the future). They may, however, be revoked at any time. As a result, applications must not assume that access tokens are valid forever.

Access tokens can be generated using the Authorization API to exchange a valid username and password pair for a new access token. As an example, the following command can be issued to generate a new access token using the Authorization API that can then be used to list all pipelines available to a user:

curl -i -u <username> -H "Content-Type: application/json" -X POST -d "{\"description\": \"Example token\", \"scopes\": [\"list:pipeline\"]}" https://api.neuroscale.io/v1/authorizations

Assuming no errors, a response similar to the one shown below will be received:

HTTP/1.1 201 CREATED
Allow: POST, OPTIONS, GET
Content-Type: application/json
Date: Tue, 27 Oct 2015 16:24:12 GMT
Server: nginx/1.1.19
Vary: Accept-Encoding
X-Frame-Options: SAMEORIGIN
Content-Length: 349
Connection: keep-alive

{
    "access_token": "3b8df1a4-32af-4f7b-8b02-3d0f561303b1",
    "created_at": 1445963052,
    "description": "Example token",
    "id": "auth_q7Jxvwr2wexz2425vXENmD",
    "object": "authorization",
    "properties": {},
    "scopes": [
        "list:pipeline"
    ],
    "updated_at": 1445963052,
    "user": "usr_ZTNc2sEjoq6JoEgPNFUg6g"
}

Access tokens are extremely sensitive — treat them just like passwords! — and should not be shared or stored in insecure places.

Using Access Tokens

Once an access token has been generated, subsequent API requests should authenticate by adding the access_token value of the returned response to the Authorization header and specifying type Bearer. For example, given the access token 3b8df1a4-32af-4f7b-8b02-3d0f561303b1, request headers should be set to Authorization: Bearer 3b8df1a4-32af-4f7b-8b02-3d0f561303b1. Or, using cURL:

curl -i -H "Authorization: Bearer 3b8df1a4-32af-4f7b-8b02-3d0f561303b1" https://api.neuroscale.io/v1/pipelines

Assuming no errors, a response similar to the one shown below will be received listing all pipelines available to the user:

HTTP/1.1 200 OK
Allow: OPTIONS, GET
Content-Type: application/json
Date: Tue, 27 Oct 2015 16:55:00 GMT
Server: nginx/1.1.19
Vary: Accept-Encoding
X-Frame-Options: SAMEORIGIN
transfer-encoding: chunked
Connection: keep-alive

{
    "count": 1,
    "data": [
        {
            "created_at": 1442367061,
            "description": "Echoes all input data.",
            "id": "pl_xTg7suuqGzFCGcnmb6Xx7f",
            "metadata": {
                "nodes": {
                    "in": [],
                    "out": []
                }
            },
            "name": "Echo (Raw)",
            "object": "pipeline",
            "owner": null,
            "parameters": {},
            "updated_at": 1442367061
        },
    ],
    "object": "list",
    "url": "/v1/pipelines"
}

Scopes

A scope defines a particular set of permissions that can be granted to an access token. Scopes are used to limit privileges (mostly for security reasons). Each API resource will state the scopes needed to make an authorized request using an access token.

The set of available scopes for a particular resource can be broken down as follows:

  • {resource-name}
  • create:{resource-name}
  • read:{resource-name}
  • update:{resource-name}
  • delete:{resource-name}
  • list:{resource-name}

For example, consider the following scopes for the Instance resource:

  • instance — Grants full read and write access to all methods of the Instance resource within the access token's user context.
  • create:instance — Grants write access to create a new Instance within the access token's user context.
  • read:instance — Grants read access to retrieve an existing Instance within the access token's user context.
  • update:instance — Grants write access to update an existing Instance within the access token's user context.
  • delete:instance — Grants write access to delete an existing Instance within the access token's user context.
  • list:instance — Grants read access to list all Instances within the access token's user context.

Scopes can be mixed and matched. For example, the following list of scopes grants an access token the ability to create, read and update instances for a user, but not to delete them:

[
    "create:instance",
    "read:instance",
    "update:instance"
]

Errors

The NeuroScale Platform API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing or invalid), and codes in the 5xx range indicate an error with NeuroScale's servers.