A developer selects a template and clicks Create. The portal produces a repository, then directs them to request an environment, ask for access and message someone for the deployment setting. The first step is self-service. Most of the journey is still coordination.
Define a complete result
For a fictional internal API, agree on the result the platform promises. It might include a repository, a test environment, a supported way to obtain access, an initial deployment and the name of the owning team. Some organizations will need an approval before a resource exists. Represent that as an explicit state with a known next step.
“Ready” should mean the developer can perform the next intended action. If an environment exists but nobody can deploy to it, say so. The portal becomes more useful when its status reflects the complete result rather than the last successful automation step.
Include the required access
Backstage’s scaffolder authorization documentation describes controls for template details, actions and tasks. Those controls can help express who may request a supported capability. The platform team still needs to connect them to the permissions required by the resulting service.
In the API example, distinguish the right to request an environment from the right to change its configuration or release into it. Give a denied request a useful explanation and a legitimate route for review. An engineer should be able to discover the next step without borrowing another person’s credentials.
Source: Backstage · Authorizing scaffolder tasks and actions.
Keep results available
Provisioning may outlast the browser session. Return a durable request record showing the resources created, their owner, current state and unresolved steps. If the operation stops halfway, explain which resources exist and what can safely be repeated.
This is where a portal can remove real support work. A developer can return to the request, understand the failure and use the supported recovery action. The platform team receives a specific operation identifier when help is needed, instead of an isolated screenshot of a spinner.
Test without step-by-step guidance
Ask an engineer unfamiliar with the template to create the test API and make its first deployment. Observe where they leave the interface to seek an answer. Each interruption reveals missing information, an access decision or an unsupported transition.
Do not turn every interruption into another portal feature. A clear owner field, a working link or an accurate status may solve the problem. The measure that matters is whether the developer can finish the promised journey and understand how the resulting service is supported.
- What exists when the request completes?
- Who owns it and who may change it?
- What is the next supported action?
- Where does the developer go when that action fails?