Skip to main content
In this guide, we’ll explore core Backstage entities: Users, Groups, APIs, Systems, Domains, Resources, and Templates. Understanding how these types interrelate will help you organize your software catalog and automate entity synchronization.
The image is a diagram with a central hexagon labeled "Entity" surrounded by six other hexagons labeled "Users," "Groups," "Systems," "Domains," "Templates," and "Resources." It illustrates different types of entities.

​
Backstage Entity Overview

​
Users

A UserEntity represents an individual—an employee, contractor, or consultant. Each user follows the same YAML structure:
  • metadata.name: unique identifier for the user
  • spec.profile: contains displayName, email, picture
  • memberOf: lists Backstage groups the user belongs to
You can synchronize users automatically from LDAP, SSO, or an HR system instead of hand-authoring each YAML file.
The image is a diagram illustrating user entity synchronization, showing connections between LDAP, Single Sign-On, and an internal HR database, with outputs to user YAML files.

​
Groups

A GroupEntity models teams, business units, or communities of interest. Groups help organize users and reflect your company’s hierarchy:
  • spec.type: e.g., business-unit, team
  • parent/children: build a hierarchy of groups
  • members: list of user metadata.name values
When syncing groups from GitHub or an identity provider, ensure the metadata.name matches the external group’s identifier to avoid duplicates.
The image is a diagram showing the concept of syncing information to create teams, with two example teams labeled "Auth Team" and "Content Team."

​
APIs

Backstage treats APIs as first-class entities. Define Component and API resources to model service interfaces:
The image is a diagram showing an "Auth Service" providing an API, which is consumed by three different services labeled Service 1, Service 2, and Service 3.
You can declare the relationship from the Component (providesApis) or from the API (apiProvidedBy).

​
Systems

A SystemEntity groups related components and resources, exposing only public APIs to consumers:
The image explains that a system is a collection of resources and components exposing public APIs, with the main benefit being the hiding of resources and private APIs between components. It includes icons representing consumers and a network.
Real-world examples:
The image illustrates a playlist management system with a mobile interface and a backend service for updating, querying, and storing playlists.
The image illustrates a real-world analogy of entity-systems, showing a banking app interface connected to a payment system and an account management system.

​
Domains

A DomainEntity defines a logical business area. Systems are grouped under domains to reflect products or services:
The image explains the concept of a domain as a collection of components serving a specific business, focusing on the "User Management Domain" with systems for authentication, user profiles, and tenants.

​
Resources

A ResourceEntity represents infrastructure—databases, message queues, buckets, or CDNs—that a system relies on:
The image is a diagram showing a "Component" that depends on a "Resource," which is connected to a database, server, and S3 bucket.

Watch Video