Skip to main content
Available from Tyk Developer Portal 1.20.0
In this guide, you build a support request form for your Portal users and add it to the Live Portal. This example shows how to use a Callout to connect a custom Page to an external service. When a signed-in Portal user submits the form, it sends their subject and description to your service and displays the returned request reference. You will add a template and a JavaScript file to a custom theme, then select that template and a Callout on a Page. The template displays the form. The Callout defines how Tyk Developer Portal sends the submission to your service without exposing its credentials in the browser.

Before You Start

You need:
  • An API Owner account to manage Callouts, Pages and themes in the Admin Portal.
  • A deployment with Callouts support and CSRF protection enabled.
  • An enabled Callout using POST, configured for a test endpoint you control. Follow Create a Callout if you do not have one.
  • An API Consumer account to test the form in the Live Portal.
  • A custom theme based on the default theme. A theme contains the templates, styles and scripts used to display the Live Portal. Follow the Create a theme instructions if you do not have one.
The service receiving the submission is the target. It must validate the submitted fields and enforce any additional authorization your workflow requires. Use test data while you develop the integration. Do not use personal or production data.

Prepare the Target

The form sends subject and description fields to Tyk Developer Portal. It wraps them in a JSON object called an envelope, with the submitted fields inside payload. See Request format for supported input formats and optional user identity. For this example, make sure Include user identity is not selected on the Callout. The target receives:
The target must return JSON or an empty response body. For this example, configure it to return HTTP 201 with Content-Type: application/json and a request reference:
If the service accepts this envelope and returns only information your Portal users may see, you can call it directly. Otherwise, you can use an intermediate API as described below.

Optional: Adapt Requests and Responses with Tyk Gateway

A Callout does not transform its request envelope into a service-specific format or filter the target’s response. You can configure an API on Tyk Gateway to perform those operations between Portal and your service. For the support-request example:
  1. Create an API on Tyk Gateway with your ticketing service as its upstream. Set the Callout’s Target URL to this API’s endpoint instead of the ticketing service URL.
  2. Configure request body transformation if the service expects a different format. Map payload.subject and payload.description from the Callout envelope to the fields your service accepts.
  3. Configure response body transformation to return only the fields needed by the Page. For this example, return the id field shown above and omit internal notes or other service details.
  4. Test successful requests and error responses. Check the full response that the browser receives, in addition to what the Page displays. Make sure sensitive fields and internal error details do not reach the browser.
The Callout authenticates with the API on Tyk Gateway. Configure authentication from Tyk Gateway to the upstream service separately. Routing through Tyk Gateway does not filter content unless you configure it to do so. Tyk Developer Portal wraps the response from the API on Tyk Gateway in its normal response envelope. Returning id preserves the response expected by this tutorial’s JavaScript. Keep the X-Callout-Request-ID header when forwarding requests to the upstream service so you can trace the request across all three systems.

Add the Page Template

The template defines the form’s fields and where the result appears. When you assign the Callout to a Page, Tyk Developer Portal supplies its submission URL to the template as .calloutAction. The form uses that URL as its action. Create views/support_request.tmpl in your custom theme:
The template checks the user and the submission URL before displaying the form. It shows a login message for anonymous visitors and an unavailable message when no usable Callout is selected. These checks improve the Page experience; the Callout endpoint enforces authentication independently. Use your deployment’s normal login flow, including single sign-on (SSO) if configured. The theme’s theme.json file lists the templates available in the Page editor. Add this entry to its existing templates array:
Keep the existing template entries. The example uses the default theme’s portal_layout and Bootstrap styles. It does not require the legacy AllowFormSubmission field.

Add Submission Handling

The JavaScript sends the form data without navigating away from the Page, then displays the result. It checks two outcomes: whether the browser request succeeded and whether the target accepted the submission. A target error can arrive at the browser with HTTP 200, so the script checks both response.ok and the returned result.ok value. See Handle the response for the full response format. The request also needs the user’s session cookie and a cross-site request forgery (CSRF) token. The token helps prevent another website from submitting a request using the user’s session. The script reads it from the Page and sends it in the X-CSRF-Token header. Never add an Admin Portal API token or a target credential to this script. Create assets/javascripts/support-request.js:
Tyk Developer Portal adds a csrf-token meta element to every layout that has closing </head> and </body> tags, including the default portal_layout in this example. It also adds a hidden csrf_token field to each form that uses method="post". This form therefore sends the token in the request body and in the header. Tyk Developer Portal removes the field before it sends the data to the target. The script converts FormData to URL-encoded data because Callouts do not accept multipart/form-data. It uses textContent to display the result as plain text, so the browser does not run it as HTML. It disables the button while the request is in progress but does not guarantee that repeated submissions create only one record. If your workflow needs that guarantee, the target must detect and handle duplicate submissions.

Upload the Theme and Create the Page

  1. Package your modified theme using the theme upload instructions.
  2. Upload it in Customise > Themes, then activate it in your test deployment.
  3. Open Customise > Pages and add a Page.
  4. Set its Page name to Support, its Path URL to /support, and its Template to Support Request.
  5. Select your enabled Callout, save the Page, and publish it.
  6. Log in as an API Consumer and open /support in the Live Portal.
  7. Submit the form and confirm that the target creates the test record.
The support request form in the Live Portal after a successful submission The expected confirmation is Request created: REQ-123., followed by a request ID. Check that the target also receives that ID in the X-Callout-Request-ID header. See Trace a request to follow the request through application logs.