Agent Local API

Introduction

The Iconik Agent runs on the user's own machine and exposes an HTTP API on localhost. It is the same API that Iconik Web, the Iconik Adobe panel and the Iconik Final Cut Pro integration use when they hand a download or an upload over to the Agent, and it is available for your own integrations as well.

The point of the API is that the Agent does the complicated parts. A download can mean traversing a collection, picking the right format on an online storage and writing a folder structure to disk. An upload means creating the asset, format, file set and file in Iconik and then running a multipart upload against whichever cloud storage the system uses. Your integration posts a request and then follows the progress.

The endpoints are listed in the API reference. This page covers how to reach the Agent and how it authenticates; Downloading and Uploading cover the two workflows.

Reaching the Agent

The Agent listens on http://localhost:6286. On macOS it also serves the same API over https://localhost:6287, because Safari refuses plain HTTP requests to localhost; other browsers can use the HTTP port. The server only accepts connections from the local machine, so the API cannot be reached from another computer.

A running Agent also serves the specification for the version that is installed, as JSON, at http://localhost:6286/docs/json. That is the one to check against if you need to know exactly what the Agent in front of you supports.

Version and features

GET /ping answers with the Agent version and the list of features that version supports. It is the way to find out whether the Agent is running at all, and whether it is new enough for what you are about to ask it to do.

curl http://localhost:6286/ping

{
  "version": "3.2.1",
  "features": ["FORMAT_DOWNLOAD", "DOWNLOAD_PLAYLISTS", "UPLOAD_BY_POST_REQUEST"]
}

FORMAT_DOWNLOAD: A specific format can be named in a download request.
DOWNLOAD_BY_POST_REQUEST: Downloads can be started by posting to the API.
AUTO_LOGIN: An auth token sent with a download request logs the user in.
SHARES: Downloads from shares are supported.
SHARE_TOKEN_AUTH: Shares can be authenticated with a share token directly.
OAUTH_LOOPBACK: The Agent can receive an OAuth redirect on loopback for a client that cannot listen on a port of its own. See Signing in with OAuth.
OPEN_IN_FCP: Downloaded files can be opened in Final Cut Pro.
UPLOAD_BY_POST_REQUEST: Files can be added to the upload queue by posting to the API.
DOWNLOAD_FILE_SET: A specific file set can be downloaded.
DOWNLOAD_VERSION: A specific asset version can be downloaded, not just the latest.
DOWNLOAD_BY_FILE_ID: A specific file can be downloaded by file id.
DOWNLOAD_ALL_FORMATS: All formats of an asset can be downloaded in one request.
DOWNLOAD_PLAYLISTS: Playlists can be downloaded.
LIST_DOWNLOADS: Downloads can be listed over the API.
LIST_UPLOADS: Uploads can be listed over the API.

Authentication

The Agent talks to Iconik as the user who is logged in to the Agent, so anything that reaches Iconik — starting a download, queueing an upload — happens with that user's permissions. Listing downloads and uploads needs no authentication at all, since those requests are answered from the Agent's own state without calling Iconik.

There are three ways to get the Agent authenticated.

From the Agent UI

The user clicks log in in the Agent, which opens a browser window against their Iconik system. The Agent keeps the token it gets back.

POST /login with an empty body returns the current user if the Agent already has a valid session, and otherwise starts the same browser login flow. Sending a token instead logs the Agent in as the user that token belongs to, against the Iconik host the Agent is configured for:

curl -X POST http://localhost:6286/login \
  -H 'Content-Type: application/json' \
  -d '{"auth": {"token": "AUTH-TOKEN", "appId": "APP-ID"}}'

{"userId": "0f0e2b0a-...-6465c664"}

The call resolves once the user is authenticated and fails if the login was cancelled.

POST /logout asks the Agent to log the current user out. It answers as soon as the request has been passed on, so a successful response does not confirm that the user was logged out, and the call does nothing at all while the Agent has no window open.

With headers on a download request

A download request can carry the credentials itself, which saves a round trip when a web page hands a download over to the Agent. Send App-ID and Iconik-Host together with one of Auth-Token, Share-Auth-Token or Share-Hash; the Agent ignores the credentials unless the application id and the host are both present. See Starting a download.

If the token belongs to the user already logged in, nothing happens and that user stays logged in. If it belongs to somebody else, the Agent asks the user to confirm the switch before it continues.

Signing in with OAuth

An application that signs the user in itself, rather than handing the job to the Agent, can use the Agent as the loopback redirect target for an OAuth authorization code flow. Send the user to Iconik's authorize endpoint with http://localhost:6286/oauth/callback as the redirect URI and your own state. The browser lands on the Agent, which shows a short page telling the user to return to your application, and keeps the result.

Collect it with GET /oauth/sessions/{state}, using the same state you sent. The answer is {"status": "complete", "code": "..."} with the authorization code to exchange for a token, or {"status": "error", "error": "..."} with an OAuth error code and an optional error_description; access_denied means the user cancelled. The result is handed out once and then forgotten, so a second poll answers 404, as does a poll before the browser has landed or after the result has expired. Abandon a sign-in with DELETE /oauth/sessions/{state}.

Keep state under 100 characters. Longer values are captured but cannot be polled back. See Authentication for the rest of the OAuth flow.

Token lifetime

While the Agent is running it keeps refreshing the token, so a long-lived integration does not have to think about expiry. If the Agent is closed, or the machine is suspended, for longer than the token's lifetime, the Agent has to be authenticated again.