What you can export from Port and what you cannot
If a renewal, a pricing change or a data residency requirement is pushing you toward an exit, start with the REST API. Port's API, documented in OpenAPI format, is the documented export path for blueprints, entities, scorecards, actions, workflows, teams, users and audit logs. Some configuration and history sit outside that path, so plan a manual capture for anything the API does not return, and confirm the exact coverage against the Port API reference before you sign off on the inventory.
The API is served from one of two regional endpoints: for Europe and for the United States. Use the endpoint that matches the tenant, since a call to the wrong region will not return your catalog. API tokens are valid for 3 hours, so script the export to request a fresh token per run, and cap request bodies at 1 MiB, so paginate large entity sets rather than assuming a single response holds everything.".replace("
Treat the export as read-only work that happens before any cutover. Take a full snapshot, record the date and the endpoint used, and store it under your own access controls. Then compare entity counts per blueprint against what Port shows in the interface, and list every item the API did not return, such as integration configuration, notification settings and custom UI layouts, so that someone owns each gap before the migration plan is approved. The mapping of blueprints and entities to Backstage kinds and catalog-info.yaml files is covered in the migration section.
Which Port data the REST API can export, and the limits
This table lists the Port data types the REST API can read, the endpoint family for each, and the documented limits that shape an export. Use it to plan which exports run in one pass and which need batching. The main takeaway is that tokens expire after 3 hours and request bodies cap at 1 MiB, so long exports need a scripted, resumable process.
| Data type | Endpoint family and output | What to plan for |
|---|---|---|
| Blueprints | Blueprint endpoints in the Port REST API, returned as JSON described by the OpenAPI spec | Export schemas first, since entities and scorecards depend on blueprint identifiers and properties |
| Entities | Entity endpoints under each blueprint, returned as JSON | Largest volume in most catalogs; read per blueprint and page through results |
| Actions and workflows | Action and workflow endpoints, returned as JSON | Record definitions and run history separately, since Backstage needs them rebuilt as Software Templates |
| Scorecards | Scorecard endpoints, returned as JSON with rule definitions | Rules map to Backstage plugins or custom checks, so keep the full rule definitions |
| Teams and users | Team and user endpoints, returned as JSON | Export group membership to map Backstage Group and User entities and sign-in resolvers |
| Audit logs | Audit log endpoints, returned as JSON | Retain for your records; confirm retention and filter options in the API reference |
| API token lifetime | Tokens are valid for 3 hours | Script token refresh so long exports do not fail midway through a run |
| Request body cap | Request bodies are capped at 1 MiB | Batch bulk writes and paginate reads; confirm pagination parameters in the API reference |
Data that does not come out cleanly and how to capture it
The Port REST API covers blueprints, entities, scorecards and audit logs, but some data never reaches it in a usable form. The cards below cover the categories that need a separate capture step, and each one names what to confirm with Port before you plan the migration.
Integration-produced entities
Entities created by Ocean-based integrations are written by a sync job, often hosted by Port or self-hosted with Helm or Docker, so their source configuration lives outside the portal data. Export the entities through the API, but also keep the integration configuration, since a resync would recreate them in Port and not in Backstage. Record which sync feeds each blueprint so you can rebuild that feed as a catalog-info.yaml generator or a Backstage ingestion source. Confirm with Port which integration settings are retrievable in your plan and region.
Rendered dashboards and widgets
Dashboards and their charts are presentation layers built from blueprint and scorecard queries, and the API returns the underlying definitions rather than rendered views. Export the query definitions and the filters that each widget applies, then recreate them as Backstage plugin views or as a separate reporting tool. Treat a screenshot as documentation only, because it carries no structure you can import. Ask Port whether dashboard definitions are included in your plan's API responses.
Historical state beyond the audit log
The audit log records who changed what and when, but it does not replay the full state of an entity at a past date. If auditors or service owners need a previous version of a catalog record, snapshot the entities on a schedule before cutover and store the JSON with dates. Keep the snapshot next to the Git history of the catalog-info files that replace it. Confirm with Port how far back the audit log retains events in your plan.
User-interface-only settings
Some configuration is set only through the portal interface, such as layout preferences, certain notification routing and display options. These settings may not appear in the OpenAPI definition, so an export script will miss them. Inventory them manually with the portal administrators and decide which ones matter for the new portal. Settings that control access or ownership must be recreated deliberately in Backstage, not copied. Ask Port which settings are exposed through the API for your account.
Access rules and team membership
Role assignments and team membership determine who can see and act on each entity, and they do not map one to one to Backstage ownership. Export users and teams through the API, then map them to Backstage Group and User entities and choose a sign-in resolver so each identity resolves consistently. Backstage advises against guest access in production, so plan that decision before users log in. Confirm with Port which role and permission data its API returns for your plan.
Export size and token refresh
Port API tokens are valid for 3 hours, so a long bulk export needs a script that requests a new token before each batch. Request bodies are capped at 1 MiB, so large entity writes into Backstage tooling must be split into batches. Log each page and token refresh so a failed run can resume without duplicating records. Use the regional endpoint that matches where your Port account is hosted.
Choosing an export path: API scripts, integration sources or Port support
A scripted pull is the route your own team controls. You authenticate against Port's REST API, list blueprints and entities, and write the results to files that you can transform into Backstage descriptors. Port's API is published in OpenAPI format and covers blueprints, entities, actions, workflows, scorecards, teams, users and audit logs. Choose the regional endpoint that matches where your Port organization lives, since Europe and the United States use different hosts. API tokens expire after a short window, so the script must refresh its token on each run rather than storing a long-lived credential. Request bodies are capped in size, so paginate large entity lists and do not expect one call to return everything.
- Coverage: The API exposes the catalog model and its records, but not every UI setting, saved view or integration configuration.
- Token handling: Store the client credentials in a secrets manager and request a fresh token at the start of each run.
- Pagination: Page through entity lists and check counts against the Port UI before you trust the export.
- Effort: Your engineers write, test and maintain the script, and they own any gaps it leaves.
- Repeatability: Schedule the script so you can re-run it during the cutover window.
Before relying on the output, confirm the endpoint, token lifetime and request limits for your plan in the Port API reference.
Many Port entities are not authored in Port. They are synced from upstream systems such as Git hosts, cloud accounts, CI tools and ticketing systems through integrations. Port's data integrations, most built on its Ocean framework, can be hosted by Port with a resync interval or self-hosted in your infrastructure with Helm or Docker. In either case, the upstream system holds the original record of who owns a service, which repository it lives in and which metadata is current. Reading from those sources, rather than from Port's copy, often gives the cleanest starting point for Backstage catalog files, because the ownership data and metadata are closest to where engineers maintain them.
- Ownership: Team and owner fields usually originate in the identity provider, the Git host or a service registry, so export from there.
- Metadata: Repository links, tags and dependencies are often defined in the source repository or CI configuration.
- Self-hosted integrations: If you run Port's integrations yourself, their configuration and mappings are already in your infrastructure and can be reused.
- Gaps: Entities that Port creates manually or through its UI will not appear in any upstream system.
- Reconciliation: Compare source-derived records with Port's entities to find drift before you write catalog-info files.
Confirm which integrations feed each blueprint and whether any of them are hosted by Port before you assume the source is available to you.
Some data may not be available through the API or from your sources, such as historical audit context, certain configuration details or records that only exist inside Port's service. In these cases, ask Port directly. A formal request sets out which blueprints, entities, scorecards or logs you need, the format you want, and the date range. This route takes the longest and depends on Port's response, so start it early in any migration plan and do not make it the only path. Treat the response as part of your evidence trail, and record what Port provided and when.
- Scope: List the specific objects and fields you need rather than asking for a full account dump.
- Timing: Request early, because the answer may arrive after your planned cutover.
- Format: Ask for machine-readable output such as JSON or YAML, so you can map it to Backstage kinds.
- Records: Keep the request and reply with your migration documentation for audit purposes.
- Fallback: Plan a manual reconstruction path for anything Port cannot supply.
Ask Port which of your requested items are available, in which format and within what timeframe, and confirm those answers in writing.
The export sequence and how to verify each step
This sequence pulls Port's catalog out in dependency order, so the schema is captured before the records that depend on it, and every stage ends with a check you can repeat. The result is a verified, checksummed archive that can seed Backstage catalog files without guesswork.
Confirm your Port regional endpoint
Check which region your Port organization is hosted in before any request is sent, because the API is served from a European endpoint at api.port.io and a United States endpoint at api.us.port.io. Send one read-only request to each candidate and keep the one that returns your organization's data. Done means the response matches a blueprint or entity you can see in the Port interface, and the chosen base URL is written into the export runbook.
Create a short-lived token and rotate it
Generate an API token scoped to read access, and record its creation time. Port API tokens are valid for 3 hours, so the export script should request a fresh token when it starts and again before expiry, rather than storing a long-lived credential in a file. Confirm rotation works by running the script across a token refresh and checking that no request fails with an authorization error. Revoke the token once the export is complete and log who held it.
Export blueprints first
Blueprints define the schema for everything else, so pull them before any entity. Save each blueprint definition, including its properties, relations and any mirror or aggregation definitions, as a separate JSON file. Verify by counting the blueprints returned by the API against the count shown in the Port interface, and by confirming that every blueprint identifier referenced in the later steps appears in this set. Keep the blueprint export as the reference for all schema checks that follow.
Export entities and check counts per blueprint
Page through entities for each blueprint, keeping identifiers, titles, properties and relations. Request bodies are capped at 1 MiB, so paginate rather than expecting one large response. Verify with record counts per blueprint, comparing the number exported with the count Port reports for that blueprint. Any mismatch should be rerun for that blueprint only before moving on. Done means every blueprint has a matching count and a file of entities that can be parsed without errors.
Run a schema diff against blueprint definitions
Compare the properties present on each exported entity with the property definitions in its blueprint. Fields that appear on entities but not in the schema, or required properties that are empty on many records, point to integration drift or data quality issues that should be resolved in Port or documented before migration. Record the diff as a file so the decision to map, fix or drop each field is traceable.
Verify entity relations with a sample comparison
Select a sample of entities that have relations, and compare each relation in the export with the same relation as shown in the Port interface. Include at least one relation that crosses blueprints, because those are the ones that become dependencies in catalog-info files. A relation that exists in Port but not in the export means a missing page or a broken query, and the export is not complete until the sample matches.
Export scorecards, teams, users and audit logs
Pull scorecards, teams and users next, since they reference entities and need the entity identifiers from the earlier steps to resolve. Audit logs come last and are kept as read-only history, not as catalog data. Check each set with a count against the Port interface and confirm that every team and user reference in the scorecards or entities resolves to a record in the export. Personal data in users and audit logs should be stored under the access controls your organization applies to identity records.
Store raw exports with checksums
Write the raw responses, unmodified, to a versioned storage location, such as an object store with versioning enabled or a Git repository used only for exports. Generate a SHA-256 checksum for every file and store the checksum list alongside the export, along with the endpoint used, the export date and the token rotation log. Verify by recomputing the checksums from the stored files in a separate step. Mapping to Backstage kinds and catalog-info.yaml files should work only from these verified copies.
Mapping blueprints and entities to Backstage kinds and catalog-info files
The core decision in this step is which Backstage kind each Port blueprint becomes. A service blueprint usually maps to a Backstage Component, an API blueprint maps to an API entity that carries its OpenAPI, AsyncAPI, GraphQL or gRPC definition, a team blueprint maps to a Group, and a user blueprint maps to a User. Blueprints that describe infrastructure, such as databases or queues, usually fit the Resource kind, and a grouping of related components usually fits System. These are common patterns, not fixed rules, so confirm each mapping with the teams who own the catalog before writing any files.
Port relations do not carry over automatically. In Backstage, links between entities are expressed as references in the descriptor, such as spec.owner on a component pointing to a Group, spec.system pointing to a System, or spec.dependsOn listing other entities. Each Port relation therefore needs a deliberate counterpart in a catalog-info.yaml file, and the reference must use the target entity's name and namespace exactly. Build a table that lists every Port relation, its Backstage field, and the entity that must exist for the reference to resolve, then check the result with the catalog's own validation before cutover.
Field-level mapping is a design decision to document for each organization. Decide which Port properties become metadata labels or annotations, which become spec fields, and which move out of the catalog entirely, such as scorecard results that are better recomputed in a plugin. Keep the mapping in version control next to the descriptor files. The exact descriptor format, required fields and allowed kinds are defined in the Backstage descriptor format documentation, and that page should be the reference your engineers use when they write files by hand or generate them from the export.
What to plan before the Port contract renewal or termination
Most of the risk in leaving Port sits in decisions made before the contract ends, not in the export itself. The cards below cover the decisions that shape the extract, the audit trail and the cutover, so they can be settled while Port still gives you full access.
Set the export window
Work backward from your contract end date and schedule a full extract well before it, then run incremental pulls until cutover. Because Port API tokens are valid for 3 hours, a long extract needs a token refresh step in the script, not a single credential pasted once. Confirm in your own agreement how many days of access remain after notice and whether access stops on the end date or on a later grace date.
Assign token and access ownership
Decide which named engineers hold the Port API credentials used for the export, and who revokes them afterward. Tokens tied to a departing employee or a personal account can fail mid-extract. Record the owner, the scope each credential needs for reads across blueprints, entities and scorecards, and the date it was revoked.
Decide retention for audit logs and exports
Port's REST API exposes audit logs, which may be the only record of who changed a blueprint or entity. Decide how long the exported audit logs, JSON files and generated catalog-info files are kept, where they are stored, and who can read them. Ask Port what happens to your data after termination and confirm the deletion terms in your own agreement.
Choose the Backstage release line
Agree whether the target portal follows the monthly main release line or the weekly next line. Under the versioning policy, the main line ships monthly and high or critical vulnerabilities are backported to releases from the last 6 months where feasible. Pick the line your platform team can upgrade within that window, and pin the Node.js version the policy lists for your chosen release.
Design identity and SSO early
Map every Port user and team to an identity provider group before cutover, because Backstage catalog ownership depends on consistent user references. Configure sign-in resolvers so each provider resolves to the same identity, and do not enable guest access in production. Confirm which of your identity providers Backstage supports directly and where Port's current role assignments must be recreated.
Run both portals during cutover
Keep Port read-only and the Backstage catalog in sync for a parallel period, so teams can compare entities and scorecards before they stop using Port. Assign one owner for each domain to confirm its catalog-info.yaml files match the exported data. Agree the switch-off date with Port in writing, and keep the final export as a frozen archive.
Questions teams ask before exporting Port data
How much effort does a full export from Port take?
Effort depends mostly on how much you have modeled in Port, not on the API itself. The main drivers are the number of blueprints, the volume of entities, how many integrations feed each blueprint, and how many teams own the data. A catalog with a handful of blueprints and clean ownership is a short exercise. A catalog with many blueprints, custom relations and scorecards spread across teams needs a mapping review before any code is written. Ask Port which of your blueprints and integrations are hosted by Port and which run in your infrastructure, because that changes where the source data comes from.
Can one engineer run the export on their own?
A single engineer who knows the Port data model and the Backstage catalog format can script most of the export. The API is documented in OpenAPI format, so pulling blueprints, entities and scorecards is straightforward. The harder part is judgment: deciding how each blueprint maps to a Backstage kind, which properties become annotations or tags, and which entities belong to which owner. Plan for review by the people who own each domain, not only the person writing the script.
What does the export need from our team?
You need four things before work starts. First, API access: a way to issue Port API tokens for the right organization and region. Second, a named Port admin who can confirm the blueprint schema and answer questions about integrations. Third, the owners of each source system, such as the people who run your Git provider, cloud accounts and CI tooling, because entities often originate there. Fourth, a Backstage target: a decision on where the portal runs, which identity provider signs users in, and who owns the catalog-info.yaml files after cutover.
Do we need a consultant for the Port export?
You do not need one for a small, well-documented catalog, but larger catalogs usually benefit from outside help with mapping and repeatable scripts. DeployOpen implements, customizes, integrates and documents self-hosted open-source platforms in your own infrastructure. Most engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before work starts, and a quote follows from that written scope. Ask any provider to state which blueprints are in scope, how entities are validated, what documentation you receive and what happens to ownership after handover.
How does the 3-hour token lifetime affect scripts that export Port data?
Port API tokens are valid for 3 hours, so a long export job can outlive its token. Build the script to request a fresh token on a schedule or when a request returns an authentication error, and store credentials in your secrets manager instead of in code. Run exports in batches per blueprint so a failed run can resume from the last completed batch. Confirm with Port how it recommends issuing tokens for automated jobs in your organization.
How does the 1 MiB request body cap affect scripted exports?
Port caps request bodies at 1 MiB, which matters when you write data back into Port, such as bulk-creating entities during a test migration. Chunk large payloads into smaller batches and keep each request under the cap. For reading, the limit applies to request bodies only, so check the API reference for pagination behavior on large list responses before you design the loop. Confirm the exact pagination parameters and any rate limits with Port, since these are not part of the supplied figures.
Where should exported data land in a Backstage portal?
Exported data should land as version-controlled files in Git, one catalog-info.yaml per component, API, resource, system, domain, group or user. Backstage reads these descriptors through its Software Catalog, and entity kinds such as Component, API, Resource and Group map from Port blueprints. Review the mapping with the owning teams before import, and keep the export script in Git so you can rerun it and see what changed. The Backstage descriptor format documentation lists the required fields for each kind.
Where to confirm the export details
Before you script anything against Port, confirm the current endpoint, token and limit details in the Port API reference, which documents the REST API in OpenAPI format. The reference covers the regional base URLs, with for Europe and for the United States, and it lists the endpoints that read blueprints, entities, scorecards, teams, users and audit logs. Choose the regional endpoint that matches where your Port organization is hosted, because a call to the wrong region will not return your catalog. The reference also states the documented token lifetime and request body cap that the export job depends on, and those are the figures to check first when a long export fails partway through. Port API reference is the starting point.
Port's API can change between releases, so treat any value you copy from documentation or a blog post, including the token lifetime, the request body limit and endpoint paths, as provisional until you read the reference on the day you run the export. Record the date you checked, the endpoints you called, and the Port API version or documentation snapshot you tested against, and store that note with the export output so a later reviewer can reproduce the run. For the target side, read the Backstage descriptor format documentation to confirm the kinds and fields your mapping will produce, and the architecture overview to confirm which core features and plugins your Backstage deployment will need to render the migrated data. Ask your Port account team to confirm any limits that are not published for your plan or region.
How DeployOpen scopes and delivers a Port data export
A Port export touches every blueprint, entity and scorecard the portal holds, so the work starts with a written scope that names what leaves Port and where it lands. The cards below cover the decisions, deliverables and boundaries that connect scoping to a verified handover.
Written scope before any export
Scope lists the blueprints, entities, scorecards and integrations to move, along with the Port region the data sits in. Agree the Europe or United States API endpoint in writing before work starts, since requests must go to the endpoint that holds the tenant. Anything left out of scope, such as audit logs or user records, should be named so it is not assumed to have moved.
Export scripts as deliverables
DeployOpen delivers the scripts that call Port's REST API and write the results to disk, including token refresh, since each API token is valid for 3 hours. The scripts also handle request body limits and pagination, so large blueprints are not silently truncated. Ask for the scripts, their run instructions and a record of which version of each was used.
Mapping rules for Backstage kinds
A mapping document shows how each Port blueprint becomes a Backstage kind such as Component, API, Resource or System, and how Port relationships become catalog references. Where a blueprint has no clean match, the document records the decision and who approved it. Review this document with your platform team before any catalog-info.yaml files are generated.
Verification reports and evidence
Each run produces a verification report comparing record counts and sampled fields between Port and the exported files. The report lists mismatches and how each was resolved. DeployOpen prepares this evidence for your own assessors, but it does not issue audit reports or attestations, which independent auditors provide.
Work inside your infrastructure
Export jobs run from machines and accounts you control, and exported data is written to storage you own, such as a private Git repository or an object store. Credentials for Port are issued to your team and scoped to read access where the export does not need writes. Confirm where logs and temporary files are kept during the run.
Quote and optional retainer
A quote follows from the written scope, so it depends on the number of blueprints, the integrations involved and the mapping decisions still open. Ongoing re-runs, catalog updates and questions after cutover can be covered by a retainer agreed separately. Ask for each deliverable to be listed with its acceptance criteria.
