What is an Imagen application?

If you want to interact with the Imagen REST API, then you must create an Imagen application using the Developer section of ImagenWeb. Creating an application generates a unique API key and secret for your application. The API key and, in some cases, the user’s access token obtained via OAuth 2.0 will be used to authenticate the application's HTTP requests to the Imagen REST API.

Each new Imagen application is given a list of scopes that define which REST resources it can use. An Imagen administrator can modify the default scope for an application.

Creating an Imagen application

1. From the ImagenWeb Developer section at https://{IMAGENWEB_HOST}/developer/index, go to the 'Your applications' page and click the Create application link.

2. Fill out the 'Create application' form. Most of the sections on this form are self-explanatory, but the 'Redirect URI' may need further explanation. The 'Redirect URI' is used as part of the OAuth 2.0 authentication process. When your application needs authorization to carry out an action on behalf of a user, your application will first redirect the user to an Imagen URL where the user will be informed what actions may be carried out by your application. If the user authorizes your application, then Imagen will return an authorization code as a query string parameter to the 'Redirect URI' that you provide here. Your application must then convert the authorization code into an access token that your application uses to make an authorized call to the Imagen REST API.

   • If you are creating a web application, set the Application type to ‘Web’ and set the Redirect URI to a secure URL provided by your application. Imagen must be able to resolve this URL to an address that it can reach and the URL must begin with https://.

   • If you are creating an installed application, for example, a desktop application, then set the Application type to 'Installed app'.

     If your application uses one of the reserved URIs, which will be displayed when you select 'Installed app' then leave the Custom redirect URI field blank. If your application has a custom URI scheme, then enter the custom URI in the 'Custom redirect URI' field.

     Explaining the reserved Custom redirect URIs

     • http://localhost: The authorization code will be returned as a query string parameter to a locally hosted website running on port 80.

     • urn:ietf:wg:oauth:2.0:oob: The authorization code will be returned in the title bar of the browser, with the page text prompting the user to copy the code and paste it in the application.

     • urn:ietf:wg:oauth:2.0:oob:auto: Identical to urn:ietf:wg:oauth:2.0:oob, but the text in the confirmation page won't instruct the user to copy the authorization code, but instead will simply ask the user to close the window.

3. Select the 'Create' link to create your new application. Once created, you can select the application from your applications page and review or edit the information that you have entered. You will also see the unique credentials that have been generated for your application. A link is provided for you to download the application data, including the credentials, as a JSON file. You can also select a link to preview the authorization page that will be presented to users of your application.

Application scopes

By default, every application will be granted readUsersData and modifyUsersData. If your application requires more scopes than these two defaults, you must contact your Imagen administrator who can change the scopes for your application in MediaControlCentre.

Disabled applications

An application can be disabled by an Imagen administrator. If this happens, you will not be able to view your application on ImagenWeb nor will you be able to use its credentials to make HTTP requests to the Imagen REST interface. It can be re-enabled by an administrator.

Character encoding in UTF-8

Imagen sends its HTTP responses encoded as UTF-8 and every request your application makes to Imagen should also be encoded as UTF-8.