API : Signed file URLs

Many responses hold the id of a file on the image, audio or document servers - an employee picture, an audio prompt, a call recording, a voicemail, a stored document. Next to such an id the response holds a signed download URL for the file. The URL works on its own, without the user's token, so it can go straight into <img src>, <audio src> or a link.

The URL property is named after the id property with Url added, and stands next to it in the same object:

An array of ids gets an array of URLs in the same order. The id property itself is unchanged.

The URL property is left out when:

• the id is null or missing
• the user may not download the file. A URL gives exactly the access the user's token gives - there is no URL for another employee's recording, for example
• the request is made with an API token with scope read
• the file is public, i.e. anybody may download it without a token (documents with access level ALL, for example). Use the id as before
• the object already has a property with that name, e.g. imageUrl on countries, which is left as it is

{
  _id: '64e9d2c5c5d9b6a8f0f1d101',
  name: 'Ole Hansen',
  picture: '64e9d2c5c5d9b6a8f0f1da01',
  pictureUrl: 'https://image.telecomx.dk/64e9d2c5c5d9b6a8f0f1da01.jpeg?exp=1794700800&sig=m7GDjWx7ahgXwQf6RF3gHzLLQylxjwy6u57uRT0fG2o'
}

https://image.telecomx.dk/<ID>.jpeg?exp=<EXP>&sig=<SIG>
https://audio.telecomx.dk/<ID>.mp3?exp=<EXP>&sig=<SIG>
https://doc.telecomx.dk/<ID>?exp=<EXP>&sig=<SIG>

Requests made to api.powernet.tv get image.powernet.tv and audio.powernet.tv URLs.

Only the id and the expiry are signed, so the rest of the URL may be changed:

• Images: another format, e.g. .png or .webp instead of .jpeg, and the image parameters such as width and height, e.g. …&width=100&height=100
• Audio: another format, e.g. .wav - see the formats on PBX audio get
• Documents are always delivered in their original format
• Download with a file name: put the name after the id, with the extension on the name, e.g. https://audio.telecomx.dk/<ID>/Message.mp3?exp=<EXP>&sig=<SIG>. This form works on all three servers - /<ID>.mp3/Message.mp3 does not work on the audio server

A URL whose id, exp or sig has been changed is refused with 403 Access Denied, and so is a URL that has expired.

The URL stays the same for a while, so a browser can cache the file, and a list of pictures is not downloaded again on every response. When a URL has expired, read the object from the API again to get a new one. A URL keeps working until it expires, also after the user has logged off.

The URL properties are never stored. An object sent back in a create or update request may still hold them - they are ignored.

URLs with ?token=<TOKEN> work as before. Properties that already hold such URLs, e.g. the playback links of PBX audio with links=true, are unchanged.