Public API Portal

The Public API Portal lets you publish API documentation for your simulations at a publicly accessible URL. Unlike Prospect Portals (which are sales-focused), the Public API Portal provides developer-facing documentation for external partners, contractors, and API consumers.

What is the Public API Portal?

The Public API Portal is a tenant-specific documentation site that:

• Displays your simulation routes as interactive API documentation
• Requires no authentication for viewers
• Updates automatically when you modify your simulation
• Lives at a shareable public URL
• Shows request/response examples with live data

Use it to share API documentation with external developers without giving them access to your SureStage workspace.

Accessing the Public Portal

Each tenant has a unique portal URL:

https://portal.surestage.com/portal/[tenant_slug]

Your tenant slug is visible in workspace settings or the portal configuration page.

Viewing Portal Content

The portal homepage lists all simulations published to the portal:

• Simulation name and description
• Base URL for making requests
• Route count
• Last updated timestamp
• Link to detailed documentation

Click any simulation to view its API documentation.

Simulation Documentation

Each simulation's portal page shows:

Overview

• Simulation name and description
• Base URL for API requests
• Authentication requirements (if any)
• Available routes summary

Route Reference

For each route:

• Method and path - e.g., GET /users/:id
• Description - What the endpoint does
• Path parameters - Parameter names and types
• Query parameters - Optional and required params
• Request headers - Expected headers (e.g., Authorization)
• Request body - Schema and example (for POST/PUT/PATCH)
• Responses - Status codes with example bodies

Try It Out

Interactive request builder for testing endpoints:

1. Fill in path parameters
2. Add query parameters
3. Set headers
4. Provide request body (if applicable)
5. Click Send Request
6. View response in real-time

The portal sends requests directly to your simulation URL.

Publishing a Simulation

Enable portal access for a simulation:

1. Open the simulation
2. Navigate to Settings > Portal
3. Toggle Publish to Public Portal
4. Configure visibility:
   • Public - Anyone with the link can view
   • Unlisted - Only accessible via direct URL (not listed on portal homepage)
5. Click Save

The simulation appears in your tenant's public portal immediately.

Portal Configuration

Access portal settings from your workspace dashboard at /portal-settings.

Tenant Portal Settings

Configure your tenant-wide portal:

• Tenant slug - Your portal subdomain (e.g., acme → portal.surestage.com/portal/acme)
• Portal name - Display name shown on the portal homepage
• Description - Introduction text for API consumers
• Logo - Upload a logo for branding
• Custom domain (Enterprise) - Use your own domain (e.g., api-docs.acme.com)

Styling

Customize portal appearance:

• Primary color - Brand color for links and buttons
• Header style - Light or dark header
• Code theme - Light or dark syntax highlighting

Changes apply immediately to the public portal.

Managing Published Simulations

View all published simulations at /portal-settings/simulations:

• Published - Currently visible in the portal
• Unlisted - Accessible via direct link only
• Draft - Not yet published

Unpublishing

Remove a simulation from the portal:

1. Open the simulation
2. Go to Settings > Portal
3. Toggle Publish to Public Portal off
4. Confirm

The simulation is removed from the portal. The simulation itself remains in your workspace.

Simulation-Specific Portal URLs

Each published simulation has a direct URL:

https://portal.surestage.com/portal/[tenant_slug]/simulation/[simulationId]

Share this link to direct developers to a specific API's documentation.

Authentication in Portal Docs

If your simulation requires authentication (e.g., API key or bearer token), the portal documentation shows:

• Required authentication method
• Header format (e.g., Authorization: Bearer <token>)
• Example authenticated requests

Portal viewers must provide their own credentials when testing endpoints via "Try It Out".

Public Portal vs. Prospect Portal

Feature	Public API Portal	Prospect Portal
Purpose	Developer documentation	Sales demonstrations
Audience	External developers	Prospects and customers
Authentication	None required to view	Optional access control
Content	Technical API reference	Product demos and use cases
Interactivity	"Try It Out" request builder	Demo scenarios and workflows
Branding	Organization branding	Customized per prospect
URL structure	/portal/[tenant_slug]	/prospect/[portal_id]

Use Public API Portal for external developer onboarding. Use Prospect Portals for sales and product demos.

SEO and Discoverability

By default, the public portal is indexed by search engines.

Control Indexing

Prevent search engine indexing:

1. Go to /portal-settings
2. Toggle Allow search engine indexing off
3. Save

A noindex meta tag is added to all portal pages.

Analytics

Track portal usage:

1. Navigate to /portal-settings/analytics
2. View metrics:
   • Page views per simulation
   • Unique visitors
   • Request volume via "Try It Out"
   • Most-viewed endpoints

Analytics help you understand which APIs external developers are most interested in.

Best Practices

Publish production-ready simulations only - Don't expose work-in-progress or test simulations publicly.

Add clear descriptions - Write route descriptions for external developers unfamiliar with your API.

Provide authentication guidance - If your simulation requires auth, document how to obtain credentials.

Use unlisted visibility for partner-only docs - Share direct links with partners without listing publicly.

Keep it updated - Portal docs auto-update, but verify accuracy before major releases.

Monitor analytics - Track which endpoints get the most attention to guide documentation improvements.

Security Considerations

• The portal displays API structure and example responses but not logs or sensitive configuration
• Authentication credentials are never shown (developers must provide their own)
• Portal viewers cannot modify simulations or access your workspace
• Rate limiting applies to "Try It Out" requests to prevent abuse
• You can unpublish simulations anytime to remove them from public view

Next Steps

• Prospect Portals - Create sales-focused demo portals
• Sharing - Share simulations with team members
• Analytics - Monitor simulation usage