2. Home
  4. Docs
  6. HTTP API of NDI
  8. Security Rules

Security Rules

To ensure network security, the HTTP API requires you to perform security authorization according to the security rules described in this section, otherwise the device will reject your HTTP request.

Unless otherwise specified, we strongly recommend that you use HTTPS (not HTTP) to execute the HTTP API. HTTP may bring you hidden security risks of leaking sensitive information (such as user name and password).

Authorization

Before you use any of the HTTP APIs described in this document, you must first obtain authorization to use the HTTP API.

The mechanism of NDI Devices authorization is briefly described as follows:

1) First of all, you need to provide a valid username and password. NDI Device needs to verify the validity of your username and password;

2) If your username and password are verified correctly, NDI Device will generate a random pair of Session ID and Authorization Token for you and return it to you in the response.

3) You must record the pair of Session ID and Authorization Token. In each of your next HTTP API requests, you must pass the Session ID and Authorization Token in the HTTP request headers or parameters. There are three alternative delivery methods:

  • Through HTTP GET / POST parameters;
  • Through the HTTP Headers fields;
  • Through HTTP cookies.

Authorization is also an HTTP API itself, but it differs from other APIs in that it does not check and verify the Session ID and Authorization Token, but generates the Session ID for you by checking the username and password you submitted And Authorization Token.

API URL

​ /api/v1/user/authorize

Request

​ Method: GET/POST

Parameter Value Description
username [STRING] ,Required A valid username to request authorization
password [STRING] ,Required The password of the authorized user

Response

Format (Example) : 

{
    "result": "ok",
    "data": {
        "session": "559dee0bd779a894618d6e044c35a3fc",
        "token": "4345cd7b092d762bd4a646a98aa9f8ff"
    }
}

Data field description:

Field Value Description
session [STRING] Random Session ID
The Session ID and Authorization Token will expire within 10 minutes after you do not have any HTTP API operations.
token [STRING] Random Authorization Token
You should record the value of session & token and pass these two values in other subsequent HTTP API requests.

Some advices:

1) Remind you! It is best not to use the built-in administrator user "admin" for API authorization, which will have serious security risks! You can create other users in the Web UI of NDI Devices and use these users to perform HTTP API requests.

2) Use HTTPS instead of HTTP to request authorization, otherwise you risk to leak your username and password!

Pass Session ID and Authorization Token in HTTP API request

If you request authorization according to the method described in 2.1, you will get the Session ID and Authorization Token generated by NDI Device for you. Next, you request any other HTTP API , NDI Device will need to verify that your Session ID and Authorization Token are legal. If you do not provide the Session ID and Authorization Token, or if you provide an illegal value, your HTTP API request will return the following error (example):

{
    "result": "auth-failed",
    "msg": "...error message..."
}

There are three ways to pass Session ID and Authorization Token:

A. [Recommended method] Pass through HTTP Request Headers

In HTTP Request Headers, add API-Session Header field to indicate Session ID, and API-Token Header field to indicate Authorization Token. E.g:

POST /api/v1/your/api HTTP/1.1
...
API-Session: 559dee0bd779a894618d6e044c35a3fc
API-Token: 4345cd7b092d762bd4a646a98aa9f8ff
...

<BODY>

If curl is used for testing, the command is as follows:

$ curl -H 'API-Session: 4345cd7b092d762bd4a646a98aa9f8ff' -H 'API-Token: 4345cd7b092d762bd4a646a98aa9f8ff' https://192.168.100.168/api/v1/your/api

B. Pass through cookies

Pass the Session ID through the HTTP Cookie field session and the Authorization Token through the field token. E.g:

POST /api/v1/your/api HTTP/1.1
...
Cookie: session=4345cd7b092d762bd4a646a98aa9f8ff;token=4345cd7b092d762bd4a646a98aa9f8ff
...

<BODY>

If curl is used for testing, the command is as follows:

$ curl -b 'session=4345cd7b092d762bd4a646a98aa9f8ff;token=4345cd7b092d762bd4a646a98aa9f8ff' https://192.168.100.168/api/v1/your/api

C. Pass through GET/POST parameters [not recommended]

If neither Method A nor Method B is applicable to you, you can also pass the Session ID and Authorization Token through the parameters of GET/POST. But we donot recommend that you use this method, because it will lessen the standardization of HTTP API parameters, making the parameters of the HTTP API seem confusing.

When it really necessary, you can pass api-session as the Session ID and api-token as the Authorization Token in the HTTP GET / POST parameters. E.g:

https://<device-ip>/api/v1/your/api?api-session=4345cd7b092d762bd4a646a98aa9f8ff&api-token=4345cd7b092d762bd4a646a98aa9f8ff

How can we help?