Authentication

All access to the getNEXT Platform REST API is authenticated using an API Key. To obtain an API Key, follow the instructions here.

Calling applications can either establish a session by making a call to the login endpoint using the API Key or provide the API Key in a header for each call made to the REST API.

Using Login and Logout

getNEXT itself uses cookie-based authentication, so when you call the login endpoint (/domain/api/1/user/login) using a POST request with the API Key as URL parameter, the response will include a cookie called GETNEXT_API_SESSION. Subsequent calls must provide this cookie to leverage the established session. To end a session, you can call the logout endpoint (/domain/api/1/user/logout).

Example curl request (assuming you have a file called API_Key.txt with the data “key=[url encoded version of the API Key]”):

Executing the following command:

curl -d "@API_Key.txt" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://www.getNEXT.com/api/1/user/login

produces the following output:

{"statusCode":0,"errorMessage":null,"warnings":null,"developerMessage":null,"moreInfo":null}

You can use the -v option to see the value of the GETNEXT_API_SESSION cookie.

Assuming curl used connection #0 for the login call, you can then end the session by executing the following command:

curl -0 -X POST https://www.getnext.com/api/1/user/logout

In both of these cases, the server returns an HTTP 200 response code to indicate success. If the key parameter is invalid or missing, the server will respond with an HTTP 401 error.

Using the API Key in a header

If you want to forgo the process of establishing a session using the login/logout mechanism, you can instead add the key as the value for the “x-api-key” header to a given call (make sure the key is not URL encoded in this case).

Example curl request (assuming you have a file called API_Key.txt with the data “x-api-key: [the api key value]” and version 7.55.0 of curl or later):

Executing the following command :

curl -H @API_Key.txt -X GET https://www.getnext.com/api/1/user/sessionInfo

produces output similar to the following:

{
    "statusCode": 0,
    "errorMessage": null,
    "warnings": null,
    "developerMessage": null,
    "moreInfo": null,
    "result": {
        "tenantName": "TenantName",
        "tenantID": "100",
        "userName": "user@example.com",
        "displayUserName": "user@example.com",
        "userID": "100",
        "privileges": [
            ...
        ],
        "overviewEnabled": true,
        "serverTime": "1517344766137",
        "statusRights": [
            ...
        ],
        "dontNotifyUser": false,
        "htmleditorEnabled": true
    }
}

If the x-api-key header is invalid or missing, the server will respond with an HTTP 403 error.