MediaValet Integrations API

openapi: 3.0.3
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. The service applies business rules, permission rules, and other data processing to standardize what is returned. Requests go to the API gateway at https://api.mediavalet.com and must carry two credentials: an OAuth 2.0 / OpenID Connect Bearer access token issued by https://login.mediavalet.com/connect/token, and a per-account subscription key in the Ocp-Apim-Subscription-Key header. Requests also carry an x-mv-api-version header to select the API version. Access requires a MediaValet subscription and registration in the MediaValet Developer Portal at https://developer.mediavalet.com.

    PROVENANCE: this definition is derived operation-for-operation from MediaValet's own published Postman collection ("MediaValet API", collection 55cc404f-b818-43ba-87c2-1a07f2a47bd9) served at https://docs.mediavalet.com/api/collections/15676803/TzRUB7XE. Paths, methods, parameters, request bodies, response status codes and examples come from that collection. Schemas are inferred from the collection's request/response example payloads and are indicative rather than authoritative.
  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).