Introduction
With the release of Multicam v10, we moved to a modern .Net version. This change result in our old method based on a simplified OAuth flow to no longer be implemented. We moved to a more simple "api key" method. You'll find on this page both methods being described.
It is important to note that the user accounts previously used are incompatible with v10 API keys.
Multicam 10+: API Key
With the API key method, there are no more password to encrypt nor a user to provide. It has been replaced by a simple API key to provide in a header named 'x-apikey'. The way to do it will vary with each client.
For example, let's take this API key set in Multicam:
So, here is an HTML page example using 'axios' to request the Multicam' systems detail. You can see that, unlike in our previous versions, the key is provided in clear and not obfuscated.
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/axios@1.1.2/dist/axios.min.js">
</script>
</head>
<body>
<div id="machineName">Machine name not available.</div>
<script lang="javascript">
const url = 'http://127.0.0.1:8082/api/application/system';
axios.interceptors.request.use((request) => {
request.headers.set('x-apikey', 'QkFqTmtDclVkQTFVaUAz');
return request;
});
axios.get(url)
.then(function (r) {
const uiMachineName = document.getElementById("machineName");
uiMachineName.innerHTML = r.data.computerName;
});
</script>
</body>
</html>
Multicam 9 and previously: user and encrypted password
To access the web API, you have two ways to authenticate requests:
- IP Address: only machine(s) with given IP will have access to the API
- User and key: you should retrieve a Token from the API with you user/key and then, pass the Token along all requests you do.
You can choose to use either or both, but at least one method must be selected.
Access token retrieval
You should issue a POST request to /Token endpoint, in form-urlencoded format
Request:
POST /Token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=password&username=john%40example.com&password=3cdbdda34160…
Parameters are:
- grant_type: fixed string with ‘password’ value.
- username: API user.
- password: API key encrypted with given RSA public key. It should be in hex or base64 format.
The Multicam public key is also available in base64:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAynqY4P5mfcYttT840IgPtQxQXZNbHnYROPl5oU8wSiC3PepF/cjYNReva+4/5RZYSOR0ZqZmTZiJbxhdF7icmydIpi3IFFtfNZwXNyDT5176EOyuhtNjLehwqFupHJ+3VYTUzqZPEMXC1jVilfIGVKJEGLgz4d5UpYrqFiodyJ/JZ+Qj1hyJV0QHSm8V9fUz6RCXFiUMo4oDEakh78eQXSM+lM1FVkfGut42C1prpyouhkIMfsYA2XOOkjiVxYOwy0TEb+/QTvJAzOzPNU1OR9s9e8Uvw8cD8O1+gc9SDNO1FfUMJFnLdG9nhTFTQusM/cGEV4TAW4op8O+LbyZonQIDAQAB
It has a RSA only cypher type.
Here's an example of using JSEncrypt to transform a multicam password to the encrypted password expected on the Multicam side ('input_myclearpassword_or_apikey' here references an input's form field):
var crypt = new JSEncrypt();
crypt.setKey("-----BEGIN PUBLIC KEY-----" +
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAynqY4P5mfcYttT840IgP" +
"tQxQXZNbHnYROPl5oU8wSiC3PepF/cjYNReva+4/5RZYSOR0ZqZmTZiJbxhdF7ic" +
"mydIpi3IFFtfNZwXNyDT5176EOyuhtNjLehwqFupHJ+3VYTUzqZPEMXC1jVilfIG" +
"VKJEGLgz4d5UpYrqFiodyJ/JZ+Qj1hyJV0QHSm8V9fUz6RCXFiUMo4oDEakh78eQ" +
"XSM+lM1FVkfGut42C1prpyouhkIMfsYA2XOOkjiVxYOwy0TEb+/QTvJAzOzPNU1O" +
"R9s9e8Uvw8cD8O1+gc9SDNO1FfUMJFnLdG9nhTFTQusM/cGEV4TAW4op8O+LbyZo" +
"nQIDAQAB" +
"-----END PUBLIC KEY-----");
var enc = crypt.encrypt($('#input_myclearpassword_or_apikey').val());
The JSEncrypt.encrypt function already returns a base64 encoded result, so the 'enc' value is to be used directly as the encrypted password on the Multicam OAuth flow.
In case of success, API returns:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"AQAAANCMnd8BFdERjHoAwE_Cl…QBYJXs1",
"token_type":"bearer",
"expires_in":1209599
}
Request authentication
Access token (access_token field) have to be added to all requests’ headers in Authorization field, with Bearer scheme:
Authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl…QBYJXs1
In case of error, API returns:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error":"invalid_grant"
}
Attached files
At the end of the article, you'll find the javascript used in our swagger page to authenticate with Multicam.
Comments
0 comments
Please sign in to leave a comment.