Recent Changes
As of version 3.16.0, several APIs will require authorization in an effort to improve their security. Authorization exists in the form of a unique API Key, which must be specified each time that an API is used. Server administrators control which users are given keys, giving them the ability to provide access to the APIs only to those users that need access.
API Key Management
All API key management is done through the Web Application. From the Config Tab, select ‘Users’ to view or modify API key settings.
Obtaining Your API Key
To obtain an API key, you must first ask your administrator to give you API access. To view your key, select the Config tab and select ‘Users’. On this screen you should see your username and the API key associated with your username. Simple copy and paste this key whenever you need to use it.
NOTE: This API key is private and connected to your account. Do not share it with other users.
Changing Your API Key
If you feel the need to change your API key, such as in the event that it has been stolen, you can regenerate your key. To generate a new API key, select the Config tab and select ‘Users’. Select your name or the edit action button to bring up your Edit User page. On the right side of this page, you will see a box labeled API Settings if you have API access. Press the “Generate New Key” button to generate a new, randomized API Key. Press the Save button to accept this change, or cancel to keep your old key.
API Access Management (Admin Only)
By default, no users are given API access. API access is granted on a per user basis through the Web Application. To grant or remove API access to a user, login as an administrator, select the Config tab, and select ‘Users’. This will show you a list of users. The users that currently have API access will have API keys in line with their names. Select the user whose API access you would like to modify. From this edit user page, you can select the checkbox labeled “API Access” to grant or remove API access for this user.
API Key Use
The use of your API key is mandatory for all APIs that require authorization. The APIs that are affected are APIs that allow you to make changes to the server or content, or view detailed information about the server. Refer to individual API pages for details.
Examples
Most, though not all, of the REST APIs that require authorization can be adjusted by simply adding ?api_key=[api_key] to the end of the url. Example:
yourserver/xml/software_version?api_key=7e14204fcce1e00152b4
Content Methods that previously required a username now instead require an API key. Example:
http://myserver/content_api/new?program_code=01&program=a1test&episode_code=009&episode=e1&description=mydescription&expected_duration=30&expected_filename=AAx&location=here&contributor=mycontrib&import_datetime=2011-04-20&delete_datetime=2012-04-20&api_key=7e14204fcce1e00152b4
For specific examples, refer to the individual API pages.
Invalid API Key
If you attempt to access a protected API without an API key or with an invalid API key, you can expect a response similar to the following:
< ?xml version="1.0" encoding="utf-8" ?>
Access Denied
