Authentication

Most of the requests to the Web API require authentication. The account must be authorized to perform the desired Action.

In most cases, you’ll want to use an Admin account. The Admin of the account is the person who signed up for the OnSIP service.

Authentication is done by establishing a session using the Action SessionCreate. The request needs to be made with parameters UserName and Password. For admins, the password is the one used to access the OnSIP Admin Portal, admin.onsip.com. If the credentials are valid, the API will respond with session information. You will use the SessionId in subsequent requests.

Session Create

Description

Used to create a new session (login the user). Returns a new SessionId for the user. The SessionId is returned in the Session node of the response.

Authentication & Authorization

Not required.

Request Parameters

Required Parameters Description
Action “SessionCreate”
Username An authentication username which references a unique user
Password A user’s login password (the password used to login to the web portal)

Result Element Schema

SessionCreate.rnc:

SessionCreate.rng

Sample Request

cURL
1
2
3
4

curl -X POST \
--data \
'Action=SessionCreate&Username=john.doe%40example.onsip.com&Password=mysuperpassword' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11

var data = new FormData();
data.append('Action', 'SessionCreate');
data.append('Username', 'john.doe@example.onsip.com');
data.append('Password', 'mysuperpassword');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-18T17:22:43+00:00</DateTime>
      <Duration>32</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>SessionCreate</Value>
        </Parameter>
        <Parameter>
          <Name>Username</Name>
          <Value>john.doe@example.com</Value>
        </Parameter>
        <Parameter>
          <Name>Password</Name>
          <Value>******</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>h68kucpnejdv2jm3bq2cmhikp5</SessionId>
      <UserId>152255</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <SessionCreate/>
  </Result>
</Response>

Session Destroy

Description

Used to destroy an existing session (logout the user).

Authentication & Authorization

Authentication Authorization
Authenticated Session none

Request Parameters

Required Parameters Description
Action “SessionDestroy”
SessionId The Id of Session to be destroyed.

Result Element Schema

SessionDestroy.rnc:

SessionDestroy.rng

Sample Request

cURL
1
2
3
4

curl -X POST \
--data \
'Action=SessionDestroy&SessionId=25h4rmjvmubl7r7e1q73msbln2' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
/*
  Session IDs always expire after 24 hours. Use the SessionRecreate
  action to prolong your live session and never store your username and
  password.
*/
​// Crude Admin API client:
var onsipApiRequest = function (data, load) {
  var onsipApi = new XMLHttpRequest();
  onsipApi.open('POST', 'https://api.onsip.com/api');
  onsipApi.addEventListener("load", function (event) {
    load(JSON.parse(onsipApi.response));
  });
  onsipApi.send(data + '&Output=json');
}
​// Step 3: Notice the new session ID.
var sessionRecreated = function (response) {
  var sessionId = response.Response.Context.Session.SessionId;
  console.log(['New Session ID', sessionId, response]);
};
​// Step 2: Get the session ID and call "SessionRecreate".
var sessionCreated = function (response) {
  var sessionId = response.Response.Context.Session.SessionId;
  console.log(['Current Session ID', sessionId, response]);
  onsipApiRequest(
    'Action=SessionRecreate&SessionId=' + sessionId,
    sessionRecreated
  );
};
​// Step 1: Create a session.
(function () {
  var username = '******';
  var password = '******';
  var data = 'Action=SessionCreate';
  data += '&Username=' + encodeURIComponent(username);
  data += '&Password=' + encodeURIComponent(password);
  onsipApiRequest(
    data,
    sessionCreated
  );
})();

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-18T17:49:25+00:00</DateTime>
      <Duration>12</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>SessionDestroy</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>25h4rmjvmubl7r7e1q73msbln2</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>false</IsEstablished>
    </Session>
  </Context>
  <Result>
    <SessionDestroy/>
  </Result>
</Response>

Topics: Developer Docs