Authentication

Most requests to the SAYMON API requires you to be authenticated. Three authentication schemes are implemented in SAYMON.

Session Authentication

In this scheme, you first request a server to create a session ID based on your login credentials. After the server creates such an ID, it sends it back to you. Then, you have to provide this session ID in the following requests in the Cookie header. Each time the server compares this ID with the initially generated and, in case the IDs match, produces a successful response.

To create a new session ID, use the Create Session ID method. When the ID is no longer required, you should delete it using the Delete Session ID method.

Example

First, create the Session ID using the Create Session ID request:

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/users/session

curl -X POST $url \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "login": "$login",
    "password": "$password"
}
EOF
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/session";

let headers = new Headers();
headers.append("Content-Type", "application/json");

let data = JSON.stringify({
    "login": login,
    "password": password
});

let requestOptions = {
    method: "POST",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/session";

let options = {
    "method": "POST",
    "hostname": saymonHostname,
    "headers": {
      "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    login: login,
    password: password
});

req.write(data);
req.end();
import requests

login = <...>
password = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/session"
body = {"login": login, "password": password}

response = requests.request("POST", url, json=body)
session_id = response.text
print(session_id)

Then, pass the session ID in the cookies:

  • Bash

  • JavaScript

  • NodeJS

  • Python

The session ID is stored in the cookies.txt file.

saymon_hostname=<...>
url=https://$saymon_hostname/node/api/users/current

curl -X GET $url -u $login:$password
curl -v --cookie cookies.txt \
-H "Content-Type: application/json" \
-X GET $url
let sessionId = <...>
let saymonHostname = <...>
let path = "/node/api/users/current";

let headers = new Headers();
headers.append("Cookie", "sid=" + sessionId);

let requestOptions = {
    method: "GET",
    headers: headers
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let sessionId = <...>
let saymonHostname = <...>
let path = "/node/api/users/current";

let options = {
    "method": "GET",
    "hostname": saymonHostname,
    "headers": {
"Cookie": "sid=" + sessionId
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.end();
import requests

session_id = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/current"
headers={"Cookie": "sid=" + session_id}

response = requests.request("GET", url, headers=headers)
print(response.text)

Basic Access Authentication

This scheme requires you to provide your login and password in the Authorization header for every request. Most examples in this documentation use this method.

Example

The examples below show how to apply the scheme for the Get Current User method:

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/users/current

curl -X GET $url -u $login:$password
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/current";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Authorization", auth);

let requestOptions = {
    method: "GET",
    headers: headers
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/current";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "GET",
    "hostname": saymonHostname,
    "path": path,
    "headers": {
        "Authorization": auth
    },
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.end();
import requests

login = <...>
password = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/current"

response = requests.request("GET", url, auth=(login, password))
print(response.text)

A successful response looks like this:

{
    "id": "your_id",
    "login": "your_login",
    "authenticationToken": "your_auth_token",
    ...
}

Token Authentication

Token authentication can be disabled in the server configuration by setting the server.user.auth_token_enabled parameter to false.

In this scheme, you first request a server to create an authentication token based on your login credentials. After the server creates such a token, it sends it back to you. Then, you have to provide this token in the following requests as a query parameter. Each time the server compares this token with the initially generated and, in case the tokens match, produces a successful response.

To create a new token, use the Create Authentication Token method. Note that after the new token is created, a previously generated one becomes invalid. When the token is no longer required, you can delete it using the Delete Authentication Token method.

Using the Token Authentication scheme, you may provide access to SAYMON API to third party users by sharing your API token with them.

Example

First, create the authentication token using the Create Authentication Token request:

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
user_id=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/users/$user_id/auth-token

curl -X POST $url -u $login:$password
let login = <...>
let password = <...>
let userId = <...>
let saymonHostname = <...>
let path = "/node/api/users/" + userId + "/auth-token";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Authorization", auth);

let requestOptions = {
    method: "POST",
    headers: headers
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let userId = <...>
let saymonHostname = <...>
let path = "/node/api/users/" + userId + "/auth-token";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "POST",
    "hostname": saymonHostname,
    "headers": {
        Authorization: auth
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.end();
import requests

login = <...>
password = <...>
user_id = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/" + \
    user_id + "/auth-token"

response = requests.request("POST", url, auth=(login, password))
print(response.text)

Then, pass the authentication token in the query parameter:

  • Bash

  • JavaScript

  • NodeJS

  • Python

saymon_hostname=<...>
api_token=<...>
url=https://$saymon_hostname/node/api/users/current

curl -X GET $url?api-token=$api_token
let authToken = <...>
let saymonHostname = <...>
let path = "/node/api/users/current?api-token=" + authToken;

let requestOptions = {
    method: "GET"
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let authToken = <...>
let saymonHostname = <...>
let path = "/node/api/users/current?api-token=" + authToken;

let options = {
    "method": "GET",
    "hostname": saymonHostname,
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.end();
import requests

api_token = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/current"
params = {"api-token": api_token}

response = requests.request("GET", url, params=params)
print(response.text)

See Also