Admin setup guide

Overview

This guide walks a Mimir tenant administrator through setting up the Pixop–Mimir integration.

At the end of this guide you will have:

A dedicated Pixop API key for the integration
A dedicated Mimir API key for the integration
Pixop workflows available in Mimir via custom actions
Metadata, option lists, and custom icons configured in Mimir
(Optional) JWT validation enabled for custom actions via JWKS

Requirements

Before you start, you need:

A Pixop enterprise team (see Pixop REST API prerequisites) and enough processing credits.
A Mimir user with Tenant administrator permission.
A Mimir tenant where your organization is authorized to use the Mimir APIs (including enabling third-party integrations) under your agreement with Fonn/Mimir (see Fonn Group API Terms of Use).
Agreement to Pixop's Terms of Service.

Note: The Pixop–Mimir integration uses Mimir APIs on your behalf using API keys you provide. Ensure your organization’s use complies with your agreement with Fonn/Mimir.

We recommend using dedicated Pixop and Mimir users for the integration. This guide shows how to create them.

Step 1 — Create a Pixop integration user and API key

Log into Pixop Studio and invite a dedicated Pixop integration user that will be used only for the Pixop–Mimir integration.
Generate an API key for the integration user via the Pixop REST API.
Store the Pixop API key securely — you’ll use it in Step 3.

Step 2 — Create a Mimir integration user and API key

Log into Mimir with an administrator user and invite a dedicated Mimir integration user that will be used only for the Pixop–Mimir integration.
Initially, add the integration user to the Organization group and ensure it has the permissions Api Keys, Folder Create, and Folder Delete (see permissions).
Log in as the integration user and generate an API key.
- Recommended:
  - Expiry date: Indefinite
  - Unused time threshold: Unspecified
- Rotate the key periodically according to your security policy.
Store the Mimir API key securely — you’ll use it in Step 3.

Step 3 — Configure the Pixop–Mimir integration

Use the Pixop Mimir Integration API to create (or update) the integration record.

Placeholders used in the example

Placeholder reference

Placeholder	Description	Where to find / how to set
`MIMIR_API_KEY`	API key used by Pixop to authenticate against your Mimir tenant	Create in Mimir under the dedicated integration user
`PIXOP_API_KEY`	API key used to authenticate the integration towards Pixop	Create for the Pixop integration user via Pixop REST API
`MIMIR_TENANT`	Identifier of the Mimir tenant this integration is configured for	Lowercase organisation name shown in Mimir My organisation
`MIMIR_NOTIFICATIONS_USER_ID`	Mimir user ID that receives notifications sent by the integration (mainly error notifications)	User ID of a Mimir administrator user
`MIMIR_ADMIN_API_KEY`	API key used during setup which requires administrator permissions (creating groups, metadata, custom actions, icons)	Create in Mimir under an admin user (must include `Tenant administrator`)
`PROCESSING_CONFIGURATION_NAME_1`	Display name for the first Pixop processing configuration shown in the Mimir UI	Pick a human-friendly label
`PROCESSING_CONFIGURATION_ID_1`	Identifier of the first Pixop processing configuration	Obtain from Pixop (via API or UI)
`PROCESSING_CONFIGURATION_NAME_2`	Display name for the second Pixop processing configuration	Same as above
`PROCESSING_CONFIGURATION_ID_2`	Identifier of the second Pixop processing configuration	Same as above

Tip: The API reference includes a built-in Try it feature, so you can configure the integration directly from your browser, without writing any client code.

Example request

curl --request PUT \
  --url https://integrations.pixop.com/mimir/v1/admin/pixop-mimir-integration \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-mimir-api-key: <MIMIR_API_KEY>' \
  --header 'x-pixop-api-key: <PIXOP_API_KEY>' \
  --header 'x-mimir-tenant: <MIMIR_TENANT>' \
  --data '
{
  "mimirNotificationsUserId": "<MIMIR_NOTIFICATIONS_USER_ID>",
  "mimirSetup": {
    "adminApiKey": "<MIMIR_ADMIN_API_KEY>",
    "pixopProcessingConfigs": [
      {
        "name": "<PROCESSING_CONFIGURATION_NAME_1>",
        "configId": "<PROCESSING_CONFIGURATION_ID_1>"
      },
      {
        "name": "<PROCESSING_CONFIGURATION_NAME_2>",
        "configId": "<PROCESSING_CONFIGURATION_ID_2>"
      }
    ]
  }
}
'

After running the request:

Review the response (example below).
Then complete any manualSteps returned by the API (Step 4).

Example response for \

{
  "integration": {
    "mimirTenant": "<MIMIR_TENANT>",
    "mimirUserId": "<MIMIR_USER_ID>",
    "createdAt": "2026-01-20T09:25:04.671737Z",
    "updatedAt": "2026-01-20T09:25:04.679755Z",
    "pixopApiKeyHidden": "*****************ABC",
    "mimirApiKeyHidden": "*****************DEF",
    "pixopMasterVideoTimeToLiveHours": 48,
    "mimirNotificationsUserId": "<MIMIR_NOTIFICATIONS_USER_ID>",
    "mimirNotificationsUserEmail": "[email protected]",
    "mimirCustomActionSecretHidden": "*****************GHI",
    "customActionsIncludeMimirUserToken": true,
    "customNotificationsEnabled": true,
    "pixopTeamId": "<PIXOP_TEAM_ID>",
    "daysToLive": 90,
    "maxAllowedProcessingsPerPixopSourceVideo": 1,
    "expiresAt": "2026-04-20T09:25:04.679755Z",
    "assignItemCommentOnIngestionFinished": true,
    "assignItemCommentOnProcessingFinished": true
  },
  "mimirSetupResult": {
    "infoMessages": [
      { "message": "Created custom icon", "data": "pixop" },
      { "message": "Created custom icon", "data": "pixopinginprog" },
      { "message": "Created custom icon", "data": "pixopingdone" },
      { "message": "Created custom icon", "data": "pixopingfailed" },
      { "message": "Created custom icon", "data": "pixopprocinprog" },
      { "message": "Created custom icon", "data": "pixopprocdone" },
      { "message": "Created custom icon", "data": "pixopprocfailed" },
      { "message": "Created custom icon", "data": "pixopdeleting" },
      { "message": "Created custom icon", "data": "pixopawaitappr" },
      {
        "message": "Created permission group",
        "data": {
          "id": "<MIMIR_TENANT>:pixopIntegrationApiUser",
          "displayName": "pixopIntegrationApiUser",
          "description": "API user for Pixop Integration",
          "permissions": [
            "general/bulkMetadataUpdate",
            "general/apiKeys",
            "userManagement/tenantInfo",
            "item/delete",
            "item/recoverDeleted",
            "item/update",
            "item/updateMetadata",
            "item/version",
            "item/promote",
            "item/createVersionRegardlessOfUpdateControl",
            "item/downloadMedia",
            "item/chooseUploadLocation",
            "item/history",
            "item/commentRead",
            "item/commentWrite",
            "item/commentStatus",
            "item/commentDeleteOwn",
            "folder/create",
            "folder/delete"
          ],
          "tenantId": "<MIMIR_TENANT>",
          "isSystemGroup": false,
          "modifiedOn": "2026-01-20T09:25:02.752Z"
        }
      },
      {
        "message": "Created permission group",
        "data": {
          "id": "<MIMIR_TENANT>:pixopIntegration",
          "displayName": "pixopIntegration",
          "description": "Users that need to use the Pixop-Mimir integration",
          "permissions": [],
          "tenantId": "<MIMIR_TENANT>",
          "isSystemGroup": false,
          "modifiedOn": "2026-01-20T09:25:02.942Z"
        }
      },
      {
        "message": "Updated custom action: <ID>",
        "data": {
          "allowedBy": { "type": "group_list", "groups": ["<MIMIR_TENANT>:pixopIntegration"] },
          "includeJWT": true,
          "icon": "file_upload",
          "url": "[REDACTED]",
          "externalId": "[REDACTED]",
          "tooltip": "Ingest in Pixop to allow Pixop video enhancement",
          "label": "Ingest in Pixop"
        }
      },
      {
        "message": "Updated custom action: <ID>",
        "data": {
          "allowedBy": { "type": "group_list", "groups": ["<MIMIR_TENANT>:pixopIntegration"] },
          "includeJWT": true,
          "icon": "queue",
          "url": "[REDACTED]",
          "externalId": "[REDACTED]",
          "tooltip": "Enhance in Pixop. Choose the Pixop enhancement configuration in the next step",
          "label": "Enhance in Pixop...",
          "metadataEnabled": true,
          "mdfSchemas": {
            "mainSchema": {
              "label": "main",
              "fields": [
                {
                  "fieldId": "pixopProcessingConfigId",
                  "type": "choice",
                  "required": true,
                  "alternatives": [],
                  "optionListId": "PixopProcessingConfigs",
                  "readOnly": false
                }
              ],
              "view": [
                {
                  "id": "pixopProcessingConfigId",
                  "fieldId": "pixopProcessingConfigId",
                  "visible": true,
                  "label": "Choose the Pixop enhancement configuration"
                }
              ],
              "isSubtype": false
            },
            "subTypes": []
          }
        }
      },
      {
        "message": "Updated custom action: <ID>",
        "data": {
          "allowedBy": { "type": "group_list", "groups": ["<MIMIR_TENANT>:pixopIntegration"] },
          "includeJWT": true,
          "icon": "thumbs_up_down",
          "url": "[REDACTED]",
          "externalId": "[REDACTED]",
          "tooltip": "Accept or reject the Pixop video enhancement price in the next step",
          "label": "Accept or reject the Pixop video enhancement price...",
          "metadataEnabled": true,
          "mdfSchemas": {
            "mainSchema": {
              "label": "main",
              "fields": [
                {
                  "fieldId": "acceptOrRejectProcessingPrice",
                  "type": "choice",
                  "required": true,
                  "alternatives": [],
                  "optionListId": "PixopAcceptOrRejectProcessingPrice",
                  "readOnly": false
                }
              ],
              "view": [
                {
                  "id": "acceptOrRejectProcessingPrice",
                  "fieldId": "acceptOrRejectProcessingPrice",
                  "visible": true,
                  "label": "Accept or reject the Pixop video enhancement price..."
                }
              ],
              "isSubtype": false
            },
            "subTypes": []
          }
        }
      },
      {
        "message": "Updated custom action: <ID>",
        "data": {
          "allowedBy": { "type": "group_list", "groups": ["<MIMIR_TENANT>:pixopIntegration"] },
          "includeJWT": true,
          "icon": "delete",
          "url": "[REDACTED]",
          "externalId": "[REDACTED]",
          "tooltip": "Delete the video in Pixop. Choose how to handle derived videos in the next step",
          "label": "Delete the video in Pixop...",
          "metadataEnabled": true,
          "mdfSchemas": {
            "mainSchema": {
              "label": "main",
              "fields": [
                {
                  "fieldId": "pixopDeleteAllDerivedVideos",
                  "type": "choice",
                  "required": true,
                  "alternatives": [],
                  "optionListId": "PixopDeleteDerivedVideosHandling",
                  "readOnly": false
                }
              ],
              "view": [
                {
                  "id": "pixopDeleteAllDerivedVideos",
                  "fieldId": "pixopDeleteAllDerivedVideos",
                  "visible": true,
                  "label": "Choose how to handle derived videos"
                }
              ],
              "isSubtype": false
            },
            "subTypes": []
          }
        }
      },
      {
        "message": "Created option list",
        "data": {
          "alternatives": [
            { "label": "AWAITING_APPROVAL", "value": "AWAITING_APPROVAL" },
            { "label": "PENDING", "value": "PENDING" },
            { "label": "PROCESSING", "value": "PROCESSING" },
            { "label": "UPLOADING", "value": "UPLOADING" },
            { "label": "DELETING", "value": "DELETING" },
            { "label": "COMPLETED", "value": "COMPLETED" },
            { "label": "FAILED", "value": "FAILED" }
          ],
          "id": "PixopStatus",
          "name": "Pixop Status",
          "modifiedOn": "2026-01-20T09:25:03.618Z"
        }
      },
      {
        "message": "Created option list",
        "data": {
          "alternatives": [
            { "label": "Accept and start processing", "value": "ACCEPT_AND_START_PROCESSING" },
            { "label": "Reject and delete version", "value": "REJECT_AND_DELETE_VERSION" }
          ],
          "id": "PixopAcceptOrRejectProcessingPrice",
          "name": "Accept or Reject Processing Price",
          "modifiedOn": "2026-01-20T09:25:03.783Z"
        }
      },
      {
        "message": "Created option list",
        "data": {
          "alternatives": [
            { "label": "Also delete derived videos", "value": "ALSO_DELETE_DERIVED_VIDEOS" },
            { "label": "Fail the request if derived videos exist", "value": "FAIL_THE_REQUEST_IF_DERIVED_VIDEOS_EXIST" }
          ],
          "id": "PixopDeleteDerivedVideosHandling",
          "name": "Delete derived videos handling",
          "modifiedOn": "2026-01-20T09:25:03.985Z"
        }
      },
      {
        "message": "Created option list",
        "data": {
          "alternatives": [
            { "label": "HDR10 upconversion", "value": "<PROCESSING_CONFIG_ID_1>" },
            { "label": "HQ live action, 4K, HDR10", "value": "<PROCESSING_CONFIG_ID_2>" }
          ],
          "id": "PixopProcessingConfigs",
          "name": "Pixop Processing Configs",
          "modifiedOn": "2026-01-20T09:25:04.086Z"
        }
      },
      {
        "message": "Created Pixop MDF",
        "data": {
          "id": "<ID>",
          "label": "Pixop",
          "active": true,
          "fields": [
            { "id": "<ID>", "fieldId": "pixopVideoId", "type": "text", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopIngestionStatus", "type": "choice", "required": false, "alternatives": [], "optionListId": "PixopStatus", "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopProcessingStatus", "type": "choice", "required": false, "alternatives": [], "optionListId": "PixopStatus", "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopProcessingPriceUsd", "type": "number", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopOriginalTitle", "type": "text", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopComparisonLink", "type": "link", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopIcon", "type": "text", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopIconTooltip", "type": "text", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopStatusIcon", "type": "text", "required": false, "alternatives": [], "readOnly": true },
            { "id": "<ID>", "fieldId": "pixopStatusIconTooltip", "type": "text", "required": false, "alternatives": [], "readOnly": true }
          ],
          "views": { "item": [], "search": [], "editing": [] }
        }
      }
    ],
    "manualSteps": [
      "Set up Custom Icon Rules in Mimir UI:\n1. Go to https://mimir.mjoll.no/settings/customicons\n2. Click the 'Rules' tab.\n3. Make sure the following rules are present (add them if missing):\n   Position 1:\n     - Icon field: pixopIcon\n     - Tooltip field: pixopIconTooltip\n   Position 2:\n     - Icon field: pixopStatusIcon\n     - Tooltip field: pixopStatusIconTooltip\n4. Click 'Save' to save the changes to the Custom Icon Rules.",
      "Please make sure that the user of the Mimir API key is a member of this permission group: '<MIMIR_TENANT>:pixopIntegrationApiUser' (https://mimir.mjoll.no/my-organisation?tab=groups&subTab=members&group=<MIMIR_TENANT>:pixopIntegrationApiUser) and member of the Organization group (https://mimir.mjoll.no/my-organisation?tab=groups&subTab=members&group=<MIMIR_TENANT>:organization).",
      "The Pixop subtype needs to be manually added to Common Metadata type here https://mimir.mjoll.no/settings/metadata:\n1. Select 'Common' in the 'Type' dropdown\n2. Click on the [+Add Field] button top right\n3. Set 'Field ID' to 'Pixop'\n4. Select 'Sub Type' in the 'Field type' dropdown\n5. Click the pencil in the 'Default value' dropdown and ensure only 'Pixop' is selected\n6. Select 'Read only' checkbox\n7. Click 'Configure permissions for this field' (person icon) and change Read permissions to Some groups: 'pixopIntegration,pixopIntegrationApiUser' and Write permissions to Some groups: 'pixopIntegrationApiUser'\n8. Click 'Save' to save the changes to Common Metadata type.",
      "The Mimir tenant is missing a JWKS URL that can validate Custom action userTokens.\nAdd it here: https://mimir.mjoll.no/doc/api.html#tag/Security/operation/putSecurity.\nSee https://docs.pixop.com/reference/mimir-admin-setup-guide for instructions."
    ]
  }
}

What the setup configures in Mimir

* Permission groups
* <MIMIR_TENANT>:pixopIntegrationApiUser (integration API user permissions)
* <MIMIR_TENANT>:pixopIntegration (controls which users can see/use Pixop metadata and custom actions)

Custom actions
- Ingest in Pixop
- Enhance in Pixop (choose processing config)
- Accept/reject price (if approval required)
- Delete in Pixop (choose derived video handling)
Metadata
- Pixop subtype including video id, ingestion/processing status, price, and fields used for custom icons
Option lists
- Pixop statuses and choices used by custom actions
- Pixop processing configs (from pixopProcessingConfigs)
Custom icons
- Pixop icon and job-status icons
Security checks (optional)
- If mimirSetup.customActionsIncludeMimirUserToken=true, the setup checks whether the tenant has a JWKS URL configured for validating user tokens

Step 4 — Complete manual steps in Mimir UI

These steps correspond to the manualSteps returned by the API. Your response may include fewer steps depending on what is already configured in your tenant.

4.1 Configure Custom Icon Rules

Go to https://mimir.mjoll.no/settings/customicons
Click the Rules tab
Ensure these rules exist (add them if missing):
- Position 1
  - Icon field: pixopIcon
  - Tooltip field: pixopIconTooltip
- Position 2
  - Icon field: pixopStatusIcon
  - Tooltip field: pixopStatusIconTooltip
Click Save

4.2 Ensure the Mimir API key user is in required groups

Make sure the user behind <MIMIR_API_KEY> is a member of:

<MIMIR_TENANT>:pixopIntegrationApiUser
https://mimir.mjoll.no/my-organisation?tab=groups&subTab=members&group=<MIMIR_TENANT>:pixopIntegrationApiUser
<MIMIR_TENANT>:organization
https://mimir.mjoll.no/my-organisation?tab=groups&subTab=members&group=<MIMIR_TENANT>:organization

4.3 Add the Pixop subtype to the Common metadata type

Go to https://mimir.mjoll.no/settings/metadata
Select Common in the Type dropdown
Click + Add Field
Set:
- Field ID: Pixop
- Field type: Sub Type
Click the pencil icon in Default value and ensure only Pixop is selected
Enable Read only
Click Configure permissions for this field (person icon) and set:
- Read: Some groups → pixopIntegration, pixopIntegrationApiUser
- Write: Some groups → pixopIntegrationApiUser
Click Save

4.4 Configure JWKS URL (required when user tokens are included)

If your Pixop–Mimir integration is using the default configuration for whether Mimir user tokens are included in custom actions (customActionsIncludeMimirUserToken=true), your Mimir tenant must be configured with a JWKS URL so Mimir can validate those JWTs. (See Mimir security considerations for an explanation of the difference between having customActionsIncludeMimirUserToken enabled or disabled.)

Mimir stores this using the Security API (PUT /auth/api/v1/security) where jwksUrl must be a JSON Web Key Set (JWKS) URL.

Security note: Your Mimir tenant will trust JWTs signed by the configured JWKS, so only point jwksUrl to a key set you explicitly intend to trust for your tenant.

Examples by identity provider

Identity provider	`jwksUrl`	What to replace / notes
AWS Cognito (User Pools)	`https://cognito-idp.<REGION>.amazonaws.com/<USER_POOL_ID>/.well-known/jwks.json`	Replace `<REGION>` and `<USER_POOL_ID>` with your Cognito user pool’s region and ID.
Microsoft Entra ID (Azure AD)	`https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys`	Replace `<TENANT_ID>` with your Microsoft Entra tenant ID.
Google	`https://www.googleapis.com/oauth2/v3/certs`	No replacement needed.

Configure JWKS URL via Mimir Security API (GET + PUT)

You can view and configure the JWKS URL using Mimir’s Security API.

1) Check current JWKS URL (GET)

Before updating anything, fetch the current Security configuration and verify whether jwksUrl is already set to the expected value.

Example cURL GET request

curl --request GET \
  --url https://mimir.mjoll.no/auth/api/v1/security \
  --header 'accept: application/json' \
  --header 'x-mimir-cognito-id-token: Bearer <MIMIR_ADMIN_API_KEY>'

curl.exe --request GET `
  --url https://mimir.mjoll.no/auth/api/v1/security `
  --header 'accept: application/json' `
  --header 'x-mimir-cognito-id-token: Bearer <MIMIR_ADMIN_API_KEY>'

If the returned jwksUrl is missing or differs from your intended value, proceed with the update below.

2) Update JWKS URL (PUT)

Use a PUT request to set the correct JWKS URL.

Example cURL PUT request

curl --request PUT \
  --url https://mimir.mjoll.no/auth/api/v1/security \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-mimir-cognito-id-token: Bearer <MIMIR_ADMIN_API_KEY>' \
  --data '
{
  "jwksUrl": "<JWKS_URL>"
}
'

curl.exe --request PUT `
  --url https://mimir.mjoll.no/auth/api/v1/security `
  --header 'accept: application/json' `
  --header 'content-type: application/json' `
  --header 'x-mimir-cognito-id-token: Bearer <MIMIR_ADMIN_API_KEY>' `
  --data '{\"jwksUrl\": \"<JWKS_URL>\"}'

Step 5 — Test the integration

Use a test item in Mimir and walk through the typical end-to-end User workflows.

Ingest
- In Mimir, right click a test item and run the custom action Ingest in Pixop.
- Confirm that:
  - the Pixop subtype fields (e.g. pixopVideoId, pixopIngestionStatus) are populated in Mimir
Wait for ingestion completion
- Wait until ingestion completes.
- Confirm that Mimir receives a status update/comment indicating ingestion finished (success or failure).
Enhance
- Run the custom action Enhance in Pixop... and choose a processing configuration.
- Confirm that a processing job is created (or that Mimir receives a comment explaining why a job was not started).
Approve price (if approval is required)
- If the workflow requires approval, run Accept or reject the Pixop video enhancement price... and choose Accept and start processing.
- If your tenant does not require approval, this step is skipped.
Wait for processing completion
- Wait until processing completes.
- Confirm that:
  - Mimir receives a completion/failure comment or notification
  - the Pixop subtype status fields reflect the final state (e.g. pixopProcessingStatus)

If anything fails, see Admin guide: Monitoring & error handling.