Authentication

Each request 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

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)

Authentication

Session Authentication

Example

Basic Access Authentication

Example

Token Authentication

Example

See Also