Ask AI
All Categories
Connectors
Configure the Iconik connector

Configure the Iconik connector

Connect with Iconik to import videos and publish captions

Last updated on June 10, 2026

Connect with Iconik to import videos and publish captions

The Iconik connector allows CaptionHub to browse and import videos from your Iconik storage, publish captions back as subtitle tracks, and automatically ingest videos based on Iconik metadata fields. Setup happens in two places: first in your Iconik account, then in CaptionHub.

Prerequisites

Before configuring the connector, ensure that:

  • You have administrator access to your Iconik account.
  • You have permission to create API users and metadata fields in Iconik.
  • You have Superuser access in CaptionHub.
  • You know which Iconik storage CaptionHub should access.

In Iconik

  1. Log in to Iconik as an administrator.
  1. Create (or designate) an API user for CaptionHub — for example captionhub@yourdomain.com. CaptionHub will authenticate and interact with Iconik using this account.
  1. Make sure the user has these roles:
      • can_read_assets
      • can_read_files
      • can_read_storages
      • can_read_webhooks, can_write_webhooks, can_delete_webhooks (only needed if you want auto-ingest)

      The API user's group also needs read on the storage (storage-level role).

  1. Open the root collection of the storage you want CaptionHub to use and set a propagating ACL giving the API user (or their group) at least read permission. Propagating ACLs ensure that newly scanned assets automatically inherit the required permissions. Without this configuration, new assets may not be visible to CaptionHub.
  1. From the API user's settings, generate an App ID and an Auth Token. Copy both somewhere safe — you'll paste them into CaptionHub in a moment.
  1. Note the storage bucket name (the underlying S3 bucket). You can find it under your storage's settings in Iconik — it's the value Iconik labels as settings.bucket.
  1. Optional — only if you want CaptionHub to auto-import videos when you tag them in Iconik:
      • In Iconik admin → Metadata fields, create a new field of type Yes/No. Name it something memorable, for example captionhub_ingest.
      • Attach the field to the metadata view applied to assets in your target storage. (If you're not sure which view, check Iconik admin → Metadata views.)

In CaptionHub

  1. Open CaptionHub in a new browser tab or window — keep your Iconik window open in case you need to copy something else.
  1. Navigate to Connectors → Iconik.
  1. Paste your credentials into the form:
      • App ID — from step 5 above.
      • Auth Token — from step 5 above.
      • Storage Bucket — from step 6 above.
  1. Optional — tick Enable auto-ingest if you want CaptionHub to pick up videos automatically when you tag them in Iconik. Leave it unticked if you only want manual browse and import. When you tick it, CaptionHub registers a webhook with Iconik on your behalf; untick it later and CaptionHub removes the webhook.
  1. Click Save.

If anything is configured incorrectly, such as an invalid token, missing role, incorrect bucket name, or missing propagating ACL, the form will identify the failed validation step and explain how to resolve it. After correcting the issue in Iconik, save the connector again. The status will update to Active once validation succeeds.

Using the Iconik connector

  • Create a project from Iconik: on the projects page, click Create new project → Iconik. CaptionHub shows the videos and audio files in your Iconik storage; pick one to ingest. CaptionHub downloads the original file (not the proxy) and creates a project from it.
  • Publish captions back to Iconik: from any project ingested from Iconik, open the Publish tab and select the languages to send. The captions appear as subtitle tracks on the asset in Iconik's player.

Set up auto-ingest

Auto-ingest allows CaptionHub to automatically create projects whenever specific assets are tagged in Iconik, removing the need for manual imports.

Auto-ingest needs two things wired up: the Enable auto-ingest checkbox on the connector (above), and an Automation that tells CaptionHub which metadata field to watch for and what project defaults to apply.

  1. In CaptionHub, go to Automations and create a new one.
  1. Under Project source, choose Iconik.
  1. Set Automatically import to Tagged.
  1. In Iconik metadata field name, type the exact name of the Yes/No field you created in Iconik (for example captionhub_ingest). Case-sensitive.
  1. Configure the project defaults you want — language profile, transcription provider, translation languages, what to do after captions are created, etc.
  1. Save and Activate the Automation.

If Enable auto-ingest on the connector is off, the Automation form shows a warning telling you so — the Automation won't fire until you tick it.

You can have several active Iconik Automations watching different metadata fields, and CaptionHub will route each tagged asset to the matching Automation. If more than one Automation matches the same asset, the Automation that was created first will be used.

In Iconik, toggle the metadata field to Yes on any video you want CaptionHub to take. A new CaptionHub project appears within a few seconds, with that Automation's defaults applied. Toggle the field back to No to stop CaptionHub from picking up further updates to that asset.

Troubleshooting

If you see an error when saving the connector, here's what to check:

  • "Auth Token is invalid or expired" — regenerate the token in Iconik admin, paste the new value into CaptionHub, save again.
  • "Iconik user is missing the 'Can read storage' role on bucket …" — the API user (or their group) doesn't have storage-level read. Fix in Iconik admin → Users / Groups, then save again.
  • "Iconik root collection has no propagating ACL — new assets won't inherit permissions" — open the root collection of your storage in Iconik admin, ACL tab, and add a propagating entry for the API user's group with at least read permission. This is one of the most commonly missed configuration steps.
  • "No Iconik storage found for bucket …" — the bucket name doesn't match any storage the API user can see. Check spelling, and confirm the user has access to the right storage in Iconik admin.
  • "Could not reach Iconik" — Iconik's API was unreachable. Try saving again in a moment.

If auto-ingest doesn't fire after toggling the metadata field to Yes:

  • Confirm Enable auto-ingest is ticked on the CaptionHub Iconik connector.
  • Confirm the Iconik metadata field name on your active Iconik Automation matches the field's name in Iconik exactly (case-sensitive).
  • Confirm the metadata field is attached to the metadata view applied to the asset.
  • Confirm the asset is in the storage you configured the connector against.
 
Did this answer your question?
😞
😐
🤩
Configure the Google Drive connector Configure the JW Player connector