The security of Netvisor's API is ensured through both software interface credentials and a unique identifier for each request.
To transfer data over the Netvisor API, the following is required:
User's API identifiers
Software partner's interface credentials
When sending requests to the Netvisor API, each request must contain specific HTTP headers. A more detailed listing of these headers is provided below.
'X-Netvisor-Authentication-Sender'
'X-Netvisor-Authentication-CustomerId'
'X-Netvisor-Authentication-PartnerId'
'X-Netvisor-Authentication-Timestamp'
'X-Netvisor-Authentication-TransactionId'
'X-Netvisor-Interface-Language'
'X-Netvisor-Organisation-ID'
'X-Netvisor-Authentication-MAC'
'X-Netvisor-Authentication-MACHashCalculationAlgorithm': SHA256
'X-Netvisor-Authentication-UseHTTPResponseStatusCodes'
Python example of MAC generation and HTTP headers using SHA256: https://support.netvisor.fi/en/support/solutions/articles/77000557880-api-authentication
The correctness of the request is ensured in the interface by the MAC identifier formed using SHA256 calculation. The SHA256 value provided in the X-Netvisor-Authentication-MAC header is calculated using all the information listed on the left in the image. The headers of requests sent to the API do not include the unique keys of the software partner or user, however, these are necessary for the SHA256 calculation. The MAC identifier is calculated separately for each request sent to the interface. If a request with the same transaction identifier has been sent to the interface previously, the interface will return an error.
Authentication HTTP Headers with Descriptions:
X-Netvisor-Authentication-Sender:
A free-form name for the integration. If a partner has multiple systems connected to Netvisor, each integration should be uniquely named. This information assists Netvisor's support and technical team in troubleshooting situations.
X-Netvisor-Authentication-CustomerId:
Software interface credentials for the customer company's user. This is a user-specific ID.
In a test environment, the software partner's employee creates the software interface credentials.
In production, the company's Netvisor user implementing the integration creates the credentials. They provide the created interface credentials and a unique key identifying the integration user to the implementer or add the credentials themselves in the integration settings.
Instructions for creating software interface credentials are available at this link.
X-Netvisor-Authentication-PartnerId:
Partner ID. Netvisor's support creates the ID and key for the partner specifically for each integration. The credentials are emailed to the partner. If the partner has multiple systems connected to Netvisor, separate partner IDs are created for each integration.
X-Netvisor-Authentication-Timestamp:
The timestamp of the integration request in ANSI format with time, GMT+0. For example, 2023-05-04 12:00:00.000.
X-Netvisor-Interface-Language:
Language information for the API affects mainly error messages in response messages. The information should be in ISO-3166 format. Possible languages are FI/SE/EN.
X-Netvisor-Organisation-ID:
The target company’s business ID. The business ID determines the company to which requests are logged or whose information is fetched. The company’s Netvisor user, whose software interface credentials are used in the integration, must have rights to this company.
X-Netvisor-Authentication-TransactionId:
A unique identifier for the request. The value must be different for each request. If a partner has previously submitted data using this identifier, the request is rejected, returning a REQUEST_NOT_UNIQUE error. The identifier is checked at the partner ID level, meaning the same identifier cannot be used with different customers.
X-Netvisor-Authentication-MACHashCalculationAlgorithm:
To accept the SHA-256 hash, the information must be provided in the headers. The value is given as SHA256.
X-Netvisor-Authentication-UseHTTPResponseStatusCodes:
We recommend all our partners add this to all requests in their integration implementations now if the interface allows. The header can be activated by setting the value to 1 for the header X-Netvisor-Authentication-UseHTTPResponseStatusCodes. This allows the use of correct status codes like 400, 401, 403, 500, and 200 in the interface responses:
200 = OK
400 = Invalid data
401 = Authentication failed
403 = Service usage error
500 = Internal server error
X-Netvisor-Authentication-MAC:
The MAC code checks the requester. All the above HTTP headers, along with the unique key provided to the integration partner and the unique key of the user's software interface credential are used to calculate the MAC code. The keys of credentials are not transmitted in HTTP headers; they are only used for MAC code calculation and verification. The MAC code is generated by combining the table information into one string, from which the SHA256 checksum is calculated. When combining information, use the '&' character between data points; the URI portion must be the same where the request is sent, including uppercase and lowercase letters.
Calculation is successful by combining the table’s data as follows.
String formed from the data:
By calculating the SHA256 checksum from the string, the MAC code is obtained as:
67fec485ef881ee00ffe4b926f8d9aebaee973ba0c8f2cadec51528026827edb
NOTE! If the URI you use contains special characters or Scandinavian letters, it must be encoded with ISO-8859-1 character set to ensure the MAC is correctly calculated and recognized by the interface.
Did you find it helpful? Yes No
Send feedback