MediaValet Integrations API

openapi: 3.2.0
info:
  title: MediaValet Integrations API
  description: The MediaValet API is a RESTful, JSON, hypermedia-driven service that supplies data to clients consuming the MediaValet cloud digital asset management (DAM) platform.
  version: '1.0'
  contact:
    name: MediaValet
    url: https://developer.mediavalet.com
  termsOfService: https://www.mediavalet.com/terms-of-service
servers:
- url: https://api.mediavalet.com
  description: MediaValet API gateway (public)
security:
- oauth2:
  - api
  subscriptionKey: []
tags:
- name: Integrations
  description: 'Third-party integration registration: apps, subscriptions, allowed origins, users and entitlements.'
paths:
  /integrations/allowed-origins:
    get:
      operationId: listWhitelistedOriginsForAnIntegration
      summary: List whitelisted origins for an integration
      description: Return every origin currently whitelisted in the CSP allowlist for the given ThirdParty integration. Used when embedding the integration in an iframe -- only origins on this list may host the embedding page. Pass the integration's id via the appId query parameter.
      tags:
      - Integrations
      parameters:
      - name: appId
        in: query
        required: false
        description: appId query parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
    post:
      operationId: whitelistAnOriginForAnIntegration
      summary: Whitelist an origin for an integration
      description: Add an origin (scheme + host + optional port) to the CSP allowlist for a ThirdParty integration. The change takes effect immediately -- no cache propagation delay. The response payload is the new allowed-origin id (UUID).
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appId:
                  type: string
                origin:
                  type: string
            example:
              appId: 00000000-0000-0000-0000-000000000000
              origin: https://your-app.example.com
      responses:
        '200':
          description: Successful response.
  /integrations/allowed-origins/batch:
    delete:
      operationId: removeOneOrMoreAllowedOrigins
      summary: Remove one or more allowed origins
      description: Remove origins by id. Pass a single-element array to remove just one. Only origins belonging to the calling tenant are affected. Response payload.removed is the count of origins removed.
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
            example:
              ids:
              - 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Successful response.
  /integrations/apps/{id}:
    delete:
      operationId: deleteAThirdPartyIntegration
      summary: Delete a ThirdParty integration
      description: Delete a ThirdParty integration owned by your tenant. Returns 404 if the integration doesn't exist or isn't owned by your tenant. Native integrations cannot be deleted via this endpoint.
      tags:
      - Integrations
      parameters:
      - name: id
        in: path
        required: true
        description: id path parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
  /integrations/apps/tenant:
    get:
      operationId: listYourTenantSIntegrations
      summary: List your tenant's integrations
      description: 'Return every integration registered to the calling tenant -- both Native (MediaValet-managed: Drupal, WordPress, Monday) and ThirdParty (customer-registered). The response payload is an array of integration objects; recordCount.totalRecordsFound is the total.'
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
  /integrations/apps:
    post:
      operationId: registerANewThirdPartyIntegration
      summary: Register a new ThirdParty integration
      description: Create a new ThirdParty integration for your tenant. Only appName is required in the request body; the other fields (appDescription, iconUrl, currentVersion) are optional partner-facing labels. The response payload.id is the new integration's identifier -- use it as the appId parameter on subsequent calls to manage allowed origins, subscriptions, and user entitlements.
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appName:
                  type: string
            example:
              appName: My ThirdParty Integration
      responses:
        '200':
          description: Successful response.
  /integrations/apps/{id}/name:
    patch:
      operationId: renameAThirdPartyIntegration
      summary: Rename a ThirdParty integration
      description: Rename a ThirdParty integration. Native integrations cannot be renamed. Returns the updated integration in the response payload.
      tags:
      - Integrations
      parameters:
      - name: id
        in: path
        required: true
        description: id path parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appName:
                  type: string
            example:
              appName: My ThirdParty Integration (renamed)
      responses:
        '200':
          description: Successful response.
  /integrations/subscriptions/app/{appId}/tenant:
    get:
      operationId: getActiveSubscriptionForAnIntegration
      summary: Get active subscription for an integration
      description: Return the active subscription for the given integration + the calling tenant. Returns 404 if no active subscription exists. Used by license-management UIs to display subscription details.
      tags:
      - Integrations
      parameters:
      - name: appId
        in: path
        required: true
        description: appId path parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
  /integrations/subscriptions/{id}/count:
    get:
      operationId: getEntitlementCountsForASubscription
      summary: Get entitlement counts for a subscription
      description: Return active-vs-total entitlement counts for a subscription. Useful for license-management dashboards that show how many seats are in use out of the total licensed.
      tags:
      - Integrations
      parameters:
      - name: id
        in: path
        required: true
        description: id path parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
  /integrations/users:
    post:
      operationId: inviteAUserIntoYourTenant
      summary: Invite a user into your tenant
      description: Create a new MediaValet user in your tenant. The user receives an invite email and completes onboarding via the standard MediaValet sign-up flow.
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userList:
                  type: array
                  items:
                    type: object
                    properties:
                      username:
                        type: string
                      firstName:
                        type: string
                      lastName:
                        type: string
                      email:
                        type: string
                      subscriptionId:
                        type: string
            example:
              userList:
              - username: partner.user
                firstName: Partner
                lastName: User
                email: partner.user@example.com
                subscriptionId: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Successful response.
  /integrations/user-entitlement/subscription/{subscriptionId}:
    get:
      operationId: listUserEntitlementsInASubscription
      summary: List user entitlements in a subscription
      description: Return every user entitlement belonging to the given subscription. Each entitlement maps one user to one subscription with a role and an active/inactive flag.
      tags:
      - Integrations
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: subscriptionId path parameter.
        schema:
          type: string
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      responses:
        '200':
          description: Successful response.
  /integrations/user-entitlement:
    put:
      operationId: updateAUserEntitlement
      summary: Update a user entitlement
      description: Update an existing user entitlement -- toggle the active flag, change the role, etc. The entitlementId field identifies the entitlement to update.
      tags:
      - Integrations
      parameters:
      - name: x-mv-api-version
        in: header
        required: false
        description: x-mv-api-version header.
        schema:
          type: string
        example: '1.2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userEntitlementList:
                  type: array
                  items:
                    type: object
                    properties:
                      entitlementId:
                        type: string
                      status:
                        type: string
            example:
              userEntitlementList:
              - entitlementId: 00000000-0000-0000-0000-000000000000
                status: active
      responses:
        '200':
          description: Successful response.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 / OpenID Connect issued by https://iam.mediavalet.com via https://login.mediavalet.com. Send the access token as a Bearer Authorization header.
      flows:
        authorizationCode:
          authorizationUrl: https://login.mediavalet.com/connect/authorize
          tokenUrl: https://login.mediavalet.com/connect/token
          refreshUrl: https://login.mediavalet.com/connect/token
          scopes:
            openid: OpenID Connect identity
            profile: User profile claims
            api: Access the MediaValet API
            api:service_principal: Service-principal (machine) access to the MediaValet API
            iam.admin: Administer MediaValet identity and access management
            iam.provisioning: Provision users and organizations
            offline_access: Obtain a refresh token
        clientCredentials:
          tokenUrl: https://login.mediavalet.com/connect/token
          scopes:
            api: Access the MediaValet API
            api:service_principal: Service-principal (machine) access to the MediaValet API
        password:
          tokenUrl: https://login.mediavalet.com/connect/token
          scopes:
            openid: OpenID Connect identity
            api: Access the MediaValet API
            offline_access: Obtain a refresh token
    subscriptionKey:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Per-account API subscription key issued through the MediaValet Developer Portal (Azure API Management).