Skip to main content

Core entities

This page describes the core entities you'll work with when integrating against the WeVideo API and how they relate to each other. We'll start with the three foundational ones: Instance, Super Instance, and User.

Instance​

An Instance is a tenant — a single WeVideo environment owned by one customer. Most integrations operate inside exactly one Instance:

  • A school or district
  • A company, department, or business unit
  • A content publisher or media partner

An Instance owns its own users, media, projects, roles, and configuration. Users created in one Instance are not visible to, and cannot be acted on from, another Instance.

Every Instance has an instanceId — a numeric identifier you'll see referenced throughout the API. Most resources (users, media items, projects) are implicitly scoped to the Instance of the calling credentials.

Each Instance defines its own roles, each role being a named bundle of permissions (import sources, publish targets, project creation rights, user-management rights, and so on). A user's capabilities inside an Instance are determined by the roles they are assigned there. See Roles for the four permission levels and how named roles map to them.

Super Instance​

A Super Instance is an umbrella that aggregates several Instances under shared administration — useful for large customers with multiple organizational units:

  • A school district that runs a separate Instance per school
  • An enterprise that runs a separate Instance per region or brand
  • Any deployment that needs centralized license pools, reporting, or admin across multiple Instances

Inside a Super Instance, each member Instance is exposed as a Building. A Building is simply the Super Instance's handle on one of its Instances — it carries a name (e.g. "Lincoln High School") and its own license/storage quota within the Super Instance's pool.

Super-Instance-level administrators can manage users, licenses, and settings across every Building without needing per-Instance credentials. Regular Instance-level API integrations are not affected by whether or not an Instance is part of a Super Instance — the Super Instance is an admin-layer construct on top.

User​

A User is an individual account. Every User:

  • Belongs to exactly one Instance (identified by the User's instanceId)
  • Has an email and a userId (the stable identifier used across the API)
  • Carries zero or more roles from the Instance they belong to, which determine what they can do

API calls that act "as a user" (issuing login tokens, generating API tokens, listing a user's media, and so on) always resolve against the User's home Instance.

Administrative capabilities that span Instances — for example, a Super Instance admin managing users across several Buildings — are expressed as special flags on the User, not as a separate user type.

How they relate​

           ┌────────────────────┐
           │   Super Instance   │   (optional umbrella for enterprise / district deployments)
           └─────────┬──────────┘
                     │ contains
                     ▼
              ┌─────────────┐
              │  Building   │   (one per member Instance, with its own name + quota)
              └──────┬──────┘
                     │ maps to
                     ▼
              ┌─────────────┐
              │  Instance   │   (tenant — owns users, media, projects, roles)
              └──────┬──────┘
                     │ has members
                     ▼
              ┌─────────────┐
              │    User     │   (belongs to exactly one Instance)
              └─────────────┘

Key rules to keep in mind when integrating:

  • A User lives in one Instance. There is no concept of the same User being a member of multiple Instances. A person who needs access to two Instances has two separate Users.
  • Roles are defined per Instance. The roles available in one Instance are independent of those in another, even when both sit under the same Super Instance.
  • Super Instances are optional. Most small and mid-size customers have a single Instance and no Super Instance. Integrations at the Instance level work identically in both cases.
  • Cross-Instance operations require Super-Instance-level admin credentials. Normal Instance admin credentials cannot see or act on resources in sibling Instances.