How to add an API licence

Related articles

Introduction

Starting with XS version 27.3, you can add and configure API licences yourself. 

XS 27.3 uses the new XS Partner API that can also be used by 3rd parties without additional settings having to be configured on the server.

This article describes how you can add a licence key for an API partner.

What you need to know before you add a licence

  • A licence becomes immediately active when you create it in backoffice. 
  • API licences are valid for one year. 
  • API licences will automatically be disabled after the licence end date.
  • To renew a licence, create a ticket with the account id and the API key. Or create a new licence instead.
  • An API licence can be disabled by disabling the user account to which the licence is attached.
  • API licences are invoiced once a year.
  • By default, the XS Partner API uses the settings that you configure for the client facing pages. So configure IPTC injection settings and comping image settings before creating a licence. Also make sure that you have uploaded a watermark for comping images.
  • It is recommended that you test the API licence before sending the details to your API partner (see below).

What you need to send to your API partner 

Your API partner will need: 

  • the API licence key,
  • the account password,
  • the comp images sizes, 

all of which you will create / configure in the steps described below.

Adding an API licence

  • Go to user management and add a user account.
  • Make sure that you write down the password. Passwords are encrypted and cannot be retrieved or reset for API accounts.
  • Save the user account.
  • In the user overview, find the account that you just created and click on it to open the user dialog.
  • On the "permissions" tabsheet, click "Make API account".
  • In the information dialog, click "Continue". You will still be able to cancel this by not saving the user account. Once the account is saved as an API account, you can no longer undo this action.
  • If you want to allow your partner agency to download high res files, then select the option "Enable download permissions automatically", otherwise select "No High resolution downloads". With the latter option selected, the API can be used to search and to get comping images but not to download high resolution files.
  • If you wantto allow your partner to download comping images without watermarks, the check the box "Comps without watermarks"
  • Specify the sizes of comping images that you want to make available (these apply to both marked and unmarked images). Sizes must be comma separated and may not be less than 100 pixels or larger than 1500 pixels. Example value: 600,800,1000. We recommend file sizes that are equal to or less than 1000 pixels to prevent having to create comping images from the high res files. 
    Your API partner needs to know which sizes you have made available. 
  • The Infradox Partner API uses the settings that you have you configured for the client facing website in backoffice when creating comping images. You can override the settings for IPTC injection and/or overlaying text on comping images without watermarks, then check the settings:
    - Never inject IPTC, regardless of Site configuration settings
    - Never overlay text on unmarked comps, regardless of Site configuration settings
  • To exclude certain files from the search results, configure the Access and Deny codes as described in the article: Search filters and Gallery access control
  • Save the account.
  • An API licence will now be created and attached to the user account. Find the account again in the user management overview and click it to open the user dialog again. 
  • On the API settings tabsheet, you'll find the API licence key. Copy this key and send it (together with the password for this user account) to your API partner.

Backoffice settings affecting the Partner API

  • Files that are retrieved with the XS Partner API are made available with the same settings as files that are made available (downloaded) from the client facing website. In casu:
  • IPTC injection is configured via Site configuration > IPTC injection. You can disable IPTC injection for API's as described above.
  • Comp images are overlayed with a watermark and/or a text overlay - as configured via Site configuration > Preview page > Comping images. And the watermark file can be uploaded via Site configuration > Website files > Watermark for comping images. 
  • Whether or not downloaded files get a file name prefix and/or if files are renamed to the original file name - can be configured via Site configuration > Website configuration > section FIle names.

Testing the API

Please refer to the manual for available commands. You should at least test if you can make a connection and create a session. To do this, open a browser and enter the following command in the url:

http://api.mywebsite.com/bin/insertapinamehere.dll?cmd=getsessionid&apikey=insertapikeyhere&pass=insertpasswordhere&user=0&territory=0

If the licence has been properly configured, the XML response will contain code 70 and a session id.

Troubleshooting

Please refer to the manual for a table of error codes.

  • If a session can't be established:
    Has the licence expired?
    Is the account to which the API licence is attached disabled or deleted?
    Did you supply the correct API key value and password?
    Is the normal / client facing website up?
  • If a comp image can't be retrieved:
    Is the requested size configured in the comp sizes property of the user account?

  • If an unmarked comp image can't be retrieved:
    Did you configure the user account to allow unmarked comp images?
    Is the requested size configured in the comp sizes property of the user account?
    Did you select the option "never overlay text on unmarked comps" in the user account?

  • If the search results are fewer than expected
    Did you check the access and deny codes that you have configured in the user account? Please read this article about this topic: Search filters and Gallery access control.

 

If these pointers don't solve your problem, then create a support ticket and provide detailed information re the problem that you are experiencing. If possible, post the XML response you are getting.

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk