API Version: Development

Authentication

Session Authentication

If a client has already authenticated using Session Authentication then no further authentication is required.
If the JS API is not being loaded, it is possible to login using a REST call directly:

Login

Path: /rest/auth/
{
    "auth": {
        "type": "auth",
        "username": "username",
        "password": "password"
    }
}
IMPORTANT: If a session cookie Red60urne is passed, then a login will affect that existing session. If no session cookie is present, then a new session is created and returned (below)
The response will be:
{
    "result": "success or fail",
    "user": {
        "id":      123,
        "login":   "loginName",
        "name":    "realName",
        "company": "company",
        "home":    "company",
        "session": "sessionCookie",
        "perms": {
            "permname": "company or yes",
            "permname": "company or yes"
        }
    }
}

Logout

Path: /rest/auth/logout
{
    "auth": {
        "type": "auth"
    }
}
IMPORTANT: A session cookie Red60urne must be passed in order to indicate which session to logout.

API keys

For stateless REST calls, API auth tokens may be used as an alternative to the above session based mechanism.
These are designed for applications with no user interface, or where the application user doesn't necessarily have individual credentials on the IPCortex Communication System.
NOTE: This is not the same as API tokens, which are used by the popup-auth mechanism internally.

Creating a token

API Tokens allow you to execute REST calls with the permissions of the user that owns the token. Before creating an API token on a user account, you should review the permissions of the role the account is assigned account to ensure that it is adequate, but not too broad for the use you intend:
From the user edit screen, edit the user tokens:
  • edit user tokens image
  • Token Management image
Add a token of type Auth Key, and copy this value for use in API calls.

Using a Token

The API token is sent in the auth attribute of the JSON request as follows:
Path: /rest/auth/
{
    "auth": {
        "type": "auth",
        "key": "long-api-key-goes-here"
    }
    ...
}
Token auth may also be sent as an HTTP header in the following format instead of embedding it in the REST request 6.3.10+:
Authorization: token auth=long-api-key