Skip to content

Core MASV concepts

Before you build with the MASV API, it helps to understand the core objects and relationships in the platform. MASV separates account and access management from the mechanics of moving files. In practice, developers usually work across five layers: platform concepts, the transfer model, workspaces, portals, and metadata.

This page gives you a mental model for how MASV fits together so you can navigate the API more easily and choose the right integration pattern for your application. MASV generally recommends using the MASV Agent or Web Uploader for transfer execution, with the REST API used to manage teams, portals, packages, links, metadata, and related workflows.

MASV at a glance

At a high level, a Team is the top-level container for your organization in MASV.

  • A Team contains users, permissions, Teamspaces, Portals, packages, and API keys.
  • A package is the transfer container that holds one or more files.
  • A Portal is a branded upload surface for receiving packages from outside contributors.
  • A Teamspace is an organizational and access-control boundary within a Team.
  • Metadata forms attach structured information to Portal submissions.

A useful way to think about MASV is this:

  • Teams define ownership, membership, and permissions.
  • Teamspaces organize work inside a Team.
  • Portals collect incoming submissions.
  • Packages hold transferred files.
  • Links expose packages to recipients for download.
  • Metadata adds business or workflow context to Portal uploads.

Platform concepts

Teams

A Team is the primary administrative boundary in MASV. Most objects you create belong to a Team directly or indirectly. For example, Portals are created under a Team, Teamspaces are created under a Team, and API keys are created for users within a Team.

When designing an integration, treat the Team as the root scope for configuration and ownership. Your application will typically start by identifying the Team it is operating against, then create or query resources such as Portals, Teamspaces, packages, or API keys within that Team.

Users and roles

Users act within a Team according to their role. MASV’s API key model is role-aware: an API key carries the same privileges as the user who created it. The docs state that users with the Owner, Admin, or Integration Manager roles can create API keys. Owners can manage all API keys for the Team, while Admins and Integration Managers can manage only the keys they create.

For developers, the important point is that MASV authorization is not just about whether a request is authenticated. It is also about whether the underlying user is allowed to perform the action. For example, Portal creation is subject to role, and Teamspace and Portal visibility can also depend on access policy and membership.

Authentication

MASV supports two main authorization patterns. For user-scoped API requests, the recommended approach is an API key. MASV also supports JSON Web Tokens (JWTs) for some user requests and for package- and transfer-scoped operations. The authorization docs also note that MASV requires TLS 1.2 or 1.3 for API connections.

In practice, this means you should think about authentication in two layers:

  1. User / Team authorization for managing resources such as Teamspaces, Portals, and API keys.
  2. Package / transfer authorization for upload and download flows.

API keys

API keys are the recommended way to authorize most application-level calls to the MASV API. They simplify integrations because you do not need to hardcode user credentials, and they do not require frequent refresh or repeated MFA prompts while active. The key value is generated once and returned only once, so it must be stored securely.

A good default architecture is to use an API key for your control-plane calls: listing resources, creating Portals, managing Teamspaces, inspecting packages, or configuring metadata forms.

Transfer model

Packages

A package is the core transfer object in MASV. A package is a set of files sent by a Team member or received by a Portal, and each package can contain multiple files. Uploads belong to a package, and the upload docs describe the package as a kind of virtual directory inside MASV.

This is one of the most important MASV concepts for developers. You do not upload “into MASV” in the abstract. You upload files as a specific package. That package then becomes the unit you manage, share, download, expire, or inspect later.

Files

Files are the contents of a package. A package may include one or many files, and file metadata is represented at the API layer while the underlying file data is stored in MASV’s storage infrastructure.

From an integration perspective, this separation is useful. Your code usually interacts with package and file metadata through API resources, while the actual upload and download operations are carried out through authorized transfer flows and MASV-managed storage endpoints.

A link represents a share of a package to one or more recipients. A package can have multiple links. The Getting Started docs explicitly state that the only way to download a package is to obtain a link from a package owner or to create a direct-download link, which itself requires package-management access. They also note that recipient link credentials are supplied out of band rather than exposed directly through the API.

This is an important security boundary. In MASV, package ownership and link possession are distinct concepts. Your application may create or manage packages, but download access is intentionally mediated through link-based mechanisms.

Downloads

MASV clients download files directly from MASV’s cloud infrastructure, and the API provides the authorized links needed to perform those downloads. MASV makes available individual file downloads as well as zip downloads for Windows/Linux and for macOS.

For developers, this means the download experience is package-centric and authorization-centric. Your application typically resolves the package or link context first, then requests or uses the appropriate authorized download path.

Workspaces

Teamspaces

A Teamspace is a way to organize a subset of Team members into a smaller group. Teamspaces are positioned as both an organizational construct and an access-control mechanism. They can be used to group people by project, client, or department and to control access to related content and workflows.

Teamspaces are especially useful when your MASV deployment spans multiple clients or internal groups. Instead of treating one Team as a flat list of users, you can create Teamspaces to reflect how work is actually structured. This improves both clarity and permissions management.

Project organization

For many developers, Teamspaces are the missing piece that makes a MASV integration feel clean. A Team gives you the enterprise boundary, but a Teamspace gives you the project boundary. If your application manages multiple productions, vendors, customers, or departments, Teamspaces are the natural place to mirror that structure.

For example, you might create one Teamspace per show, client account, or ingest workflow. Packages, Portals, and membership can then be aligned to that structure so users see only the work relevant to them. MASV’s Portal settings also support Teamspace-based scoping for Member access.

Portals

What's a MASV Portal?

A Portal is MASV’s external-facing upload surface. Portals are represented as resources created under a Team, and are a simple, organized way to request and receive files from clients, colleagues, and content creators. Each Portal has a unique subdomain.

Portals are often the first MASV concept external users encounter. They let someone submit files into your MASV environment without exposing your internal administration model directly. In that sense, a Portal is both a user experience surface and an integration boundary.

Vendor and contributor uploads

Portals are designed for external contribution workflows. A sender can upload into a Portal without needing a MASV account unless the Portal owner has configured additional restrictions. This makes Portals a strong fit for vendor delivery, client submissions, partner collaboration, media ingest, and other managed inbound workflows.

From a developer perspective, the main value is that Portals let you standardize how incoming content is received. Rather than building a public upload experience from scratch, you can create and configure Portals through the API and then integrate them into downstream workflows.

Metadata collection

Portals are also the primary place where MASV collects structured metadata from external senders. A Portal can have a custom metadata form associated with it, and when that form exists, a form response is required before the Portal package can be created. MASV can then deliver that metadata in JSON, CSV, XML, and email-body formats.

This is what makes Portals more than simple upload pages. They are workflow intake surfaces. A Portal submission can contain not just files, but also the descriptive and routing information your downstream systems need.

Portal security

Portals support several security and access patterns. The Portal API includes support for upload access codes. The help docs also describe upload password protection, download password protection, Teamspace assignment, and private Portal access rules. Additionally, some download or upload flows may require user authentication depending on how the Portal or link is configured.

For developers, the key design point is that Portal access is configurable. Some Portals are intended to be broadly reachable with minimal friction. Others are tightly controlled for authenticated users, Teamspace members, or holders of a password or access code. Your application should treat Portal security as part of the business workflow, not as a fixed platform behavior.

Metadata

Metadata forms

A metadata form is a structured form attached to a Portal that collects information from the sender during upload. MASV’s help docs describe it as a way for partners and clients to include descriptive or technical metadata such as package name, content type, project reference IDs, or other information needed for tracking or integration with downstream systems like MAMs and Enterprise cloud and on-premises storage systems.

The developer docs define the workflow clearly: an admin creates a form, configures its fields, the sender submits a response, the package is created with that response, and the upload is completed. When the package is finalized, the metadata is delivered according to the selected output formats.

Metadata fields

MASV provides default fields for new metadata forms, including Sender Email, Package Name, and Package Description. The help docs also note that forms can collect multiple data types, including checkbox, dropdown select, radio button, email, and date picker fields.

That matters because it gives developers a predictable way to collect structured intake data. You can use fields not only for human-readable context, but also for operational values such as routing codes, production IDs, file categories, delivery targets, or downstream workflow selectors.

Metadata APIs

The metadata APIs allow Team admins to create and manage custom metadata forms on Portals. They also let you define delivery formats and integrate form data into package creation workflows. MASV can place metadata files at the root of the received Portal package and can also include the data in notification emails.

This makes metadata a first-class integration surface. Instead of treating it as a note attached to a transfer, you can treat it as structured input to downstream automation, storage routing, indexing, or MAM ingestion.

One caveat from the docs is important: MASV Agent automations do not support Portals with custom metadata forms when user interaction is required to fill them out. If your workflow depends on unattended automation, design your intake path accordingly.

Putting the concepts together

A typical MASV workflow looks like this:

  1. Your application authenticates with an API key associated with a Team user.
  2. It creates or manages Team-level resources such as Teamspaces and Portals.
  3. External contributors upload through a Portal.
  4. Their submission creates a package containing one or more files.
  5. If the Portal uses a metadata form, the sender submits structured metadata as part of the package creation flow.
  6. Recipients access the package through download links or direct-download flows, subject to MASV’s authorization model.

Once you understand that sequence, the rest of the MASV API becomes easier to navigate. Teams and roles govern who can do things. Teamspaces organize who sees what. Portals collect inbound files. Packages hold those files. Links expose them for download. Metadata adds the context needed for real workflows.

Choosing the right MASV building block

Use a Team when you need a top-level administrative scope. Use a Teamspace when you need project or group-level organization inside that Team. Use a Portal when you need a controlled intake surface for external senders. Use a package when you are thinking about the actual unit of transfer. Use a link when you are thinking about how recipients access downloads. Use metadata forms when uploads need to carry business context alongside files.

Next steps

After reading this page, most developers should continue with:

  • Authorization, to choose between API keys and web tokens.
  • Portals, if you are building inbound submission workflows.
  • Uploads and Downloads, if you are implementing transfer flows directly.
  • Teamspaces, if you need project-level access control.
  • Custom Metadata, if you need structured intake and routing data.