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).