Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tyk.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

Documentation-Only Products let you publish API documentation in the Developer Portal without creating any access policy or issuing credentials. Consumers can browse your documentation, explore the interactive playground, and review specifications, with no “Request Access” button and no Plan selection. In this section we will refer to those Products that can be combined with Plans to issue credentials as Regular Products.

​
When to use a Documentation-Only Product

  1. Pre-release APIs: publish an OpenAPI spec or GraphQL schema before the API is available for consumption, so developers can plan integrations ahead of launch.
  2. Partner previews: share API documentation with external partners in a controlled catalog without opening up live access.
  3. Deprecated API archives: keep documentation accessible for consumers on legacy integrations after the API has been retired, without issuing new credentials.
  4. Conceptual overviews: provide architectural guides, best practices, or integration patterns that have no corresponding live endpoint.
  5. Educational resources: structure learning content about your API ecosystem using Getting Started guides and product descriptions.

​
Prerequisites

  • Access to the Developer Portal Admin UI with an API Owner role
  • An existing Catalog to publish the product to
  • An OpenAPI Description file in JSON or YAML format, or a GraphQL SDL file (.graphql, .graphqls, .gql, or JSON format)
For an overview of API Products, see API Products. For steps to create a standard API Product with live access, see the API Products page.

​
Create a Documentation-Only Product

There is no explicit documentation-only toggle in the Admin UI. A Product becomes documentation-only automatically when no APIs are selected on the APIs tab. No access policy will be created in the connected Tyk Dashboard, so no credentials can be generated for the Product.
  1. Navigate to API Products In the Admin Portal, go to Developer Portal > API Products and select Add new API Product.
  2. Skip API selection Open the APIs tab. Do not select any APIs from the list. Skip to the next tab. This is what makes the Product documentation-only. APIs tab on the Add API Product page, showing the default empty state with no APIs selected and the inline note to skip this tab for documentation-only products
  3. Add documentation Open the Documentation tab and select Add API specification:
    1. For REST APIs: choose OpenAPI, then upload a JSON or YAML file or provide a URL.
    2. For GraphQL APIs (available from v1.15.0): choose GraphQL SDL, then upload an SDL file (.graphql, .graphqls, .gql, or JSON). File upload only, URL is not supported for GraphQL SDL.
    In the Specification Alias field, enter a label for this document. Use underscores or camelCase, do not use hyphens. Documentation tab showing an uploaded OpenAPI specification with the Specification Alias field filled in
  4. Provide the Product details Open the Details tab and complete the following:
    1. Product name: use a clear, descriptive name. Consider a convention such as “[DOCS] Payment Integration Guide” so admins can distinguish documentation-only Products at a glance.
    2. Catalog display name and Product summary: the summary appears as the tile description in the Live Portal.
    3. Product description: make clear in the description that this Product is documentation-only and consumers cannot request access.
    4. Product image (optional): JPG or PNG, recommended 700x400 pixels.
    5. Publish API Product to catalogue: select one or more Catalogs.
  5. Add Getting Started Guides (optional) Open the Getting Started Guides tab to create Markdown or HTML pages. These appear on the product’s Get Started tab in the Live Portal and are the right place for tutorials, integration walkthroughs, and conceptual overviews.
  6. Save and verify Select Save Changes, then open the Live Portal and confirm:
    1. The Product appears in the assigned Catalog.
    2. The API specification tab renders your uploaded specification.
    The API specification tab showing a rendered OpenAPI specification in Redoc, with endpoint navigation on the left and schema details on the right

​
What consumers see

Documentation-only Products appear in the Catalog alongside regular Products, but with key differences: The Overview, API specification, and Get Started tabs are fully accessible, but
  1. There is no Request Access button.
  2. There are no Plans available to select.
  3. No credentials can be requested or issued.
Live Portal page for a documentation-only Product, showing the Overview, API specification, and Get Started tabs with no Request Access button This behavior is enforced by the Portal: the Product has no associated access policy in Tyk Dashboard, and the UI hides all access-request components when a Product is documentation-only.

​
Convert a Product’s type

You do not need to recreate a Product to change its type: this is dynamic, based on whether any API access is configured. Convert a documentation-only Product into a regular Product
  1. Open the Product in the Admin Portal and navigate to the APIs tab.
  2. Select a Provider, an authentication method, and one or more APIs to which the Product should grant access.
  3. Select Save Changes.
The Portal creates a new access policy in Tyk Dashboard so that it becomes a regular Product. Consumers can now request access and receive credentials to consume the APIs in the Product. Convert a regular Product to documentation-only
  1. Open the Product and navigate to the APIs tab.
  2. Remove all selected APIs.
  3. Select Save Changes.
When you convert a regular Product to documentation-only, the associated access policy in Tyk Dashboard is immediately deactivated. Any existing credentials issued for this Product stop working at that point. If you re-add APIs later, the policy is reactivated and previously issued credentials resume working.

​
Troubleshooting

Check whether the Specification Alias contains a hyphen. If it does, rename the alias using underscores or camelCase, then re-upload the file.
This was a bug in versions prior to v1.16.0. Upgrade to v1.16.0 or later. On older versions, the UI elements appear but are non-functional for documentation-only Products.
This was a bug in versions prior to v1.14.1. The Portal attempted to update a non-existent access policy. Upgrade to v1.14.1 or later to perform this conversion without errors.
Confirm the Product is published to at least one Catalog, and that the consumer’s Organisation has access to that Catalog. Documentation-only Products follow the same Catalog visibility rules as regular Products.